@swifty.js/swifty 0.0.1 → 0.0.2

package/docs/ch13.md

@@ -1,320 +0,0 @@
-# Subagent
-
-一个大的重构任务中, 插入一个小的更新 README.md 任务: Agent 上下文污染
-
-## 关键洞察: Agent 也是一种工具
-
-Agent 和 Tool 抽象同构, 可以将 Agent 包装为 Tool, 注册到 ToolRegistry
-
-<!-- 源码: src/tools/types.ts -->
-
-```ts
-export type ToolCategory = "read" | "write" | "command";
-
-interface Tool {
-  name: string; // Subagent 的名字
-  description: string; // Subagent 的描述
-  category: ToolCategory;
-  deferred?: boolean;
-  system?: boolean;
-  schema(): ToolSchema; // 参数: Subagent 的任务
-  // 返回 Subagent 的执行结果
-  execute(ctx: ToolContext, args: Record<string, unknown>): Promise<ToolResult>;
-}
-```
-
-## properties (parameters)
-
-<!-- 源码: src/subagent/agent-tool.ts -->
-
-```json
-{
-  "name": "code-review",
-  "description": "负责代码审查的 subagent",
-  "prompt": "",
-  "subagent_type": "", // 预定义的 agent 角色, 例如 explore, plan, code-review
-  "model": "", // 模型
-  "run_in_background": false, // 同步执行/异步执行
-  "isolation": "", // undefined | "worktree", 见 ch14
-  "team_name": "" // 见 ch14
-}
-```
-
-- 多 Agent 框架 (CrewAI、AutoGen): 中心化编排
-  - AutoGen 的 GroupChat 使用 GroupChatManager, 按策略决定 agent chat 顺序
-  - CrewAI 使用 Crew 对象编排 agent 和任务调度
-- Swifty: 主从模式, coding 场景下主从模式更稳定, 避免多 Agent 循环等待
-
-## 两种创建模式
-
-- 预定义的 subagent (Definition-based): 预定义的 subagent 角色, 无对话历史
-- fork 的 subagent (Fork-based): spawn (fork) 一个 subagent, 继承父 Agent 的完整对话历史
-
-### 预定义的 subagent (Definition-based)
-
-subagent_type 不能为空, 是预定义的 subagent 角色
-
-示例: .swifty/agents/code-review.md
-
-负责代码审查的 subagent 不能再 fork 一个 subagent、不能写文件、不能执行 Bash 命令, 是只读的代码审查专家
-
-<!-- 源码: src/subagent/loader.ts -->
-
-```md
----
-name: code-review
-description: 负责代码审查的 subagent
-disallowed_tools:
-  - EditFile
-  - WriteFile
-  - Bash
-max_turns: 20
----
-
-你是一个负责代码审查的 subagent
-
-## 职责
-
-...
-
-## 规则
-
-...
-```
-
-### fork 的 subagent (Fork-based)
-
-- subagent_type 为空时, 创建 fork 的 subagent
-- 典型场景: 将一个 react 类组件迁移到函数组件后, fork 3 个 subagent 迁移剩余的类组件
-- 降低成本: fork 的 subagent 和 父 Agent 使用相同的 tools、system、messages (prompt cache 按前缀匹配, 顺序是 tools -> system -> messages), fork 的 subagent 首次 LLM API 请求可以命中 prompt cache, 降低 input_tokens 成本
-
-> 继承父 Agent 的完整对话历史
-
-1. 复制父 Agent 的完整对话历史
-2. 对话历史的最后一条 assistant 消息中, 对「请求调用 AgentTool 的 tool_use 内容块 tu」, push 一个 tool_result 内容块, 保持 messages 格式 (user 和 assistant 两个 role 交替出现)
-3. 将 Agent 的任务指令作为 user 消息, 追加到对话历史, 使用 `<fork_boilerplate />` 标签包裹对 subagent 的行为约束
-
-```json
-{
-  "tool_use_id": "${tu.tool_use_id}",
-  "content": "(tool execution interrupted by fork)",
-  "is_error": false
-}
-```
-
-> 为什么需要使用 `<fork_boilerplate />` 标签包裹对 subagent 的行为约束?
-
-fork 的 subagent 继承父 Agent 的 system prompt, system prompt 可能包含: "你可以创建 subagent", "你需要向用户确认" 等, 使用 `<fork_boilerplate />` 覆盖继承的默认行为
-
-```md
-<fork_boilerplate>
-You are a forked worker process. You are NOT the main agent.
-Rules (non-negotiable):
-
-1. Do NOT fork again.
-2. Do NOT converse, ask questions, or request confirmation.
-3. Use tools directly: read files, search code, make changes.
-4. Stay strictly within your assigned task scope.
-5. Final report must be under 500 characters, starting with "Scope:".
-   </fork_boilerplate>
-
-Your task: ${prompt}
-```
-
-fork 的 subagent 必须后台异步运行, 执行结束后使用 `<task-notification />` 标签包裹执行结果, 作为一条 user 消息注入到主 agent 的上下文 (TODO)
-
-> 为什么 fork 的 subagent 必须后台异步运行?
-
-1. fork 的场景是主 agent 分发多个子任务, 并发执行
-2. fork 的 subagent 继承父 Agent 的完整对话历史, 首次 API 请求耗时长; 前台同步等待, 父 Agent 阻塞, 用户体验很差
-
-> 定义式 subagent 默认前台同步运行
-
-定义式 subagent 默认前台同步运行, 除非
-
-- subagent 配置的 frontmatter 中指定 `background: true`
-- 调用 subagent 时指定 `run_in_background: true`
-
-```yaml
-name: code-review
-description: 负责代码审查的 subagent
-disallowed_tools:
-  - EditFile
-  - WriteFile
-  - Bash
-max_turns: 20
-background: true
-```
-
-## 选择哪种创建模式: Definition-based / Fork-based
-
-- 如果任务通用、固定角色、固定职责, 例如 plan 指定计划、explore 代码探索、code-review 代码审查, 使用定义式 subagent, 指定 subagent_type:
-  - 可以精确控制 subagent 的能力边界
-  - 可以限制 subagent 调用的工具
-  - 可以指定一个更小更快的模型: haiku, sonnet, deepseek...
-- 如果任务不通用、与主 agent 的当前工作高度相关, 例如: 迁移一个组件的 useImperativeHandle 从 react18 到 react19, fork 3 个 subagent 迁移剩余的类组件, 使用 fork 的 subagent, subagent_type 为空
-
-## 上下文隔离
-
-- 基础设施共享: API Key、LLM API 连接池、工具集、MCP、Skill、Hook
-- 权限 (permissionMode) 隔离
-- 文件系统: 默认共享, 使用 `isolation: "worktree"` 时隔离
-
-## Subagent markdown 配置
-
-<!-- 源码: src/subagent/loader.ts -->
-
-|                              | 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 subagent. Mirrors Go's AgentMemoryScope. */
-export type AgentMemoryScope = "user" | "project" | "local";
-
-export interface AgentDefinition {
-  name: string; // Agent type
-  description: string; // When to use
-  tools?: string[];
-  disallowedTools?: string[];
-  systemPromptOverride?: string;
-  maxTurns?: number;
-  model?: string;
-  permissionMode?: PermissionMode; // "default" | "acceptEdits" | "plan" | "bypassPermissions"
-  background?: boolean;
-  isolation?: "worktree";
-  initialPrompt?: string;
-  omitMarkdown?: boolean;
-  skills?: string[];
-  /** Memory scope — "user" | "project" | "local" */
-  memory?: AgentMemoryScope;
-  mcpServers?: string[];
-  // ...
-}
-```
-
-<!-- 源码: src/subagent/loader.ts -->
-
-Agent 定义文件, 优先级从低到高
-
-- 内置级: Swifty 内置 (BUILTIN_AGENTS)
-- 用户级: ~/.swifty/agents/
-- 项目级: ${workDir}/.swifty/agents/
-
-## Subagent 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
-
-## Subagent 不能继续 spawn
-
-<!-- 源码: src/subagent/tool-filter.ts -->
-
-1. 全局 subagent: 工具黑名单 ALL_AGENT_DISALLOWED_TOOLS, 该黑名单包含 Agent, AskUserQuestion, ...
-2. 后台异步运行的 subagent: 工具白名单 ASYNC_AGENT_ALLOWED_TOOLS, 该白名单不包括 AgentTool、AskUserQuestion
-3. 自定义 subagent: 额外工具黑名单 CUSTOM_AGENT_DISALLOWED_TOOLS
-4. Subagent markdown 配置 frontmatter 中的 tools、disallowed_tools
-
-具体的
-
-<!-- 源码: src/subagent/tool-filter.ts -->
-
-- 预定义的 subagent 不能继续 spawn: 通过全局 subagent 工具黑名单 ALL_AGENT_DISALLOWED_TOOLS, 该黑名单包含 Agent, AskUserQuestion, ...
-- fork 的 subagent 不能继续 fork
-  - fork 一个 subagent 会克隆主 agent 的 tools, 克隆得到的 AgentTool 有 querySource 标记, 如果某个 agent 的 AgentTool 有 querySource 标记, 则是 fork 的 subagent, 不能继续 fork
-  - 如果对话历史中包含 fork 标记 `<fork_boilerplate />`, 则是 fork 的 subagent, 不能继续 fork
-- 后台异步运行的 subagent 不能继续 spawn: 通过硬编码的工具白名单 ASYNC_AGENT_ALLOWED_TOOLS, 该白名单不包括 AgentTool、AskUserQuestion
-
-## 后台异步运行模式
-
-1. 调用 AgentTool 时指定 `run_in_background: true`, subagent 以后台异步任务启动, 主 agent 收到 subagent 的 agentId 和 async_launched 状态
-2. 前台同步运行的 subagent 120s 还未结束, 自动切换到后台异步运行
-3. 按 esc 键将前台同步运行的 subagent 手动切换到后台异步运行
-4. fork 的 subagent 无条件后台异步运行
-
-swifty 没有管理后台异步任务的 Slash Command, 后台异步任务通过 4 个内置工具暴露给 agent:
-
-- TaskList 任务列表
-- TaskGet 获取某个任务的状态或结果
-- TaskCreate 创建任务, 提供给 hook 使用
-- TaskUpdate 更新任务状态
-
-## 内置 subagent_type
-
-### Explore
-
-<!-- 源码: src/subagent/definition.ts -->
-
-```md
----
-name: explore
-description: You are a code exploration expert. This is a read-only exploration task.
-disallowed_tools: ["EditFile", "WriteFile"]
-model: haiku
-permission_mode: plan
----
-
-你是代码探索专家, 这是一个只读探索任务
-
-禁止: 创建文件、修改文件、删除文件、提问
-
-工具调用策略:
-
-- 使用 Glob 搜索文件
-- 使用 Grep 搜索内容
-- 使用 ReadFile 读取指定路径的文件
-- 只允许执行只读的 Bash 命令
-- 尽可能并发调用多个工具以提高效率
-```
-
-### Plan
-
-<!-- 源码: src/subagent/definition.ts -->
-
-```md
----
-name: plan
-description: You are a software architect. This is a read-only planning task.
-disallowed_tools: ["EditFile", "WriteFile"]
-permission_mode: plan
----
-
-你是软件架构师, 这是一个只读规划任务
-
-禁止: 创建文件、修改文件、删除文件、提问
-
-工作流程
-
-1. 理户需求
-2. 探索代码库, 了解项目约定、开发范式
-3. 设计方案
-4. 输出计划, 划分里程碑, 明确风险
-```
-
-### General Purpose
-
-<!-- 源码: src/subagent/definition.ts -->
-
-```md
----
-name: general-purpose
-description: 你是 Swifty 的 Subagent, 不是主 agent
----
-```

package/docs/ch14.md

@@ -1,152 +0,0 @@
-# worktree
-
-文件系统隔离
-
-subagent 的会话被持久化到 .swifty/worktree_session.json, 如果 swifty 进程崩溃, 重新启动时可以通过 --resume 切换回 worktree 会话, 跳过 git worktree add 创建 worktree
-
-## git 命令的环境变量
-
-<!-- 源码: src/worktree/env.ts -->
-
-```bash
-# 禁止 git 提示输入用户名或密码
-GIT_ASKPASS=""
-# 禁止 git 的交互式提示
-GIT_TERMINAL_PROMPT=0
-```
-
-## git worktree 命令
-
-<!-- 源码: src/worktree/worktree.ts -->
-
-```bash
-git worktree add <worktreePath> <worktreeBranch>
-
-# -B: worktree 分支存在时, 强制覆盖旧的 worktree 分支
-git worktree add -B <worktreeBranch> <worktreePath> <baseBranch>
-# 等价于
-git branch -f <worktreeBranch> <baseBranch>
-git worktree add <worktreePath> <worktreeBranch>
-```
-
-- 需要 slug 安全验证, 防止路径遍历 ../../etc/password
-- worktree 目录在 .swifty/worktrees
-- 分支名加 `worktree-` 前缀
-
-<!-- 源码: src/worktree/worktree.ts -->
-
-```js
-const worktreeDir = join(projectRoot, ".swifty", "worktrees", slug);
-const branch = `worktree-${slug}`;
-```
-
-脆弱实现
-
-<!-- 源码: src/worktree/worktree.ts -->
-
-如果 worktree 目录已存在, 则跳过 git worktree add 创建 worktree, 直接复用
-
-- 先读 worktree 目录下的 .git 指针文件, 得到 gitdir 路径
-- 再读 HEAD 文件, 如果 HEAD 是符号引用 ref: refs/head/..., 则继续读 refs 得到 commit SHA
-  git worktree add 创建 worktree 对于大型仓库需要数秒: 检出全量文件树、写入 worktree 目录
-
-后续优化
-
-```bash
-# 列出所有 worktree、路径、分支、commit SHA
-git worktree list --porcelain
-# 查询某个 worktree 当前的 commit SHA
-git -C <worktree-path> rev-parse HEAD
-```
-
-## worktree 创建后
-
-```bash
-# 列出被 .gitignore 忽略的文件和目录
-# --directory: 如果整个目录被忽略, 则只打印目录
-git ls-files --other --ignored --exclude-standard --directory
-```
-
-<!-- 源码: src/worktree/worktree.ts, src/worktree/setup.ts -->
-
-`performPostCreationSetup` worktree 创建后执行:
-
-1. 复制 `.swifty/` 配置目录到 worktree
-2. 设置 git hooks: 先使用 `.husky/`, 再使用 `.git/hooks/`, 通过 `git config core.hooksPath` 共享主仓库的 hooks (源码: src/worktree/worktree.ts)
-3. 安装依赖 (pnpm install、go mod tidy): 源码缺陷 TODO
-4. 读取 `.worktreeinclude` 文件 (每行一个路径, 跳过空行和 `#` 注释), 将 include 的文件和目录复制到 worktree; 跳过以 / 开头或包含 .. 的路径, 防止路径遍历
-
-## 进入 worktree
-
-<!-- 源码: src/tools/enter-worktree.ts -->
-
-- 不切换进程级 cwd: 防止后台异步 subagent、agent team 并发调用 Bash 工具切换进程级 cwd;
-- 将 worktree 路径保存到 session 状态, (sub)agent 调用 Bash、ReadFile、WriteFile 等工具时, 显式的从 `session.worktreePath` 拿到 worktree 路径
-
-## 退出 worktree
-
-<!-- 源码: src/worktree/worktree.ts, src/worktree/changes.ts -->
-
-```bash
-# 是否有未 commit 的修改
-git status --porcelain
-
-# 是否有新增的 commit (相对 worktree 创建时的 HEAD)
-git rev-list --count ${headCommit}..HEAD
-```
-
-- `hasWorktreeChanges` 两种实现:
-  - worktree.ts: 先执行 `git status --porcelain`, 再对比当前 HEAD SHA 与 `headCommit` (worktree 创建时的 HEAD) 是否相同, 不使用 `git rev-list` <!-- 源码: src/worktree/worktree.ts -->
-  - changes.ts: 执行 `git rev-list --count ${headCommit}..HEAD` 统计新增 commit 数量, `headCommit` 是 worktree 创建时的 HEAD
-- 是否删除 worktree: worktree 中是否有未 commit 的修改、是否有新增的 commit
-- 清空 session 状态
-
-## 清理过期的 worktree
-
-<!-- 源码: src/worktree/worktree.ts, src/worktree/cleanup.ts -->
-
-- 进程崩溃、用户强制退出, 会导致 .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 并且推送到远端, 则可以自动清理
-
-## worktree 与 subagent
-
-<!-- 源码: src/tools/enter-worktree.ts, src/worktree/worktree.ts -->
-
-subagent 使用 `isolation: "worktree"` 时, subagent 的启动流程
-
-1. 创建 worktree
-2. 创建 subagent, 将 worktree 路径保存到 session 状态
-3. 运行 subagent
-4. subagent loop 结束后在 worktree 中提交
-5. 离开、清理 worktree
-6. 返回结果给主 agent
-7. 主 agent cr, 决定是否合并
-
-```ts
-export function buildWorktreeNotice(parentCwd: string, wtPath: string): string {
-  return (
-    `You are working in a git worktree at: ${wtPath}\n` +
-    `The parent project is at: ${parentCwd}\n` +
-    `Changes made here are isolated from the parent working tree.`
-  );
-}
-```
-
-- 你 (subagent) 继承父 agent 的对话历史
-- 你 (subagent) 在 git worktree 工作, 你需要翻译父 agent 对话历史中的路径为 worktree 中的路径, 修改文件前重新读取文件
-
-> 考虑以下场景
-
-subagent 在 worktree 中修改并提交了 server.ts, 主 agent 期望将该 subagent 的变更merge/rebase/cherry-pick 到主分支; Swifty 没有内置的 merge/rebase/cherry-pick 工具, 主 agent 调用 Bash 工具, 执行 `git merge/rebase/cherry-pick`
-
-为什么 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