@huskky/sakurai

v0.2.0

Published

a month ago

Sakura 是一个独立的中文 Coding Agent CLI。它基于 Pi Coding Agent SDK 提供的模型会话、流式交互、多模态输入、会话管理和基础代码工具，重点补充项目理解、需求确认、代码审查、回归检查和受控 Git 交付流程。

0High
0Medium
0Low

huskky

Sakura Coding Agent

Sakura 适合处理以下日常开发事务：

阅读陌生代码，识别项目用途、入口和模块关系，输出结构树。
将文字或图片需求拆成 Bug、功能新增、非功能要求、验收标准和待确认问题。
在需求和计划确认后修改代码，并在提交前审查完整 Diff。
根据变更影响选择回归检查，分类报告失败原因。
在独立开发分支上完成 pull、commit、push，并通过单独确认门禁进入下一步。
使用本地知识索引、项目记忆、用户记忆和当前工作区会话历史辅助工作。

当前版本：0.2.0。Sakura 是本地 CLI，尚未提供 Web UI、IDE 插件或 OS 级沙箱。

快速开始

环境要求

Node.js >=22.19.0 <27
pnpm 11.8.0（开发时使用）
Bun >=1.3.14 <2（使用 Sakura OpenTUI 时需要）
Sakura OpenTUI 当前支持 macOS 和 Linux；没有 Bun 时可改用 Pi TUI
一个已配置到 Sakura 目录的 Provider/模型

在项目目录运行

cd /path/to/sakura
pnpm install
pnpm start

pnpm start 会先构建 TypeScript，再启动当前目录作为工作区的 Sakura。也可以在构建后直接运行：

pnpm build
node bin/sakura.js

从 npm 安装并在任意目录使用 `sakura` 或 `skr`

发布后可直接从 npm 全局安装：

npm install -g @huskky/sakurai

如果你是在本地源码目录验证，也可以执行 npm install -g .。安装完成后，两个命令都会出现在系统 PATH 中：

sakura --version
skr --version

全局安装后，在目标项目目录中直接运行：

cd /path/to/your/project
sakura
# 或
skr

如果仍然出现 command not found，先检查 npm 全局 bin 是否在当前 shell 的 PATH 中：

npm prefix -g
command -v sakura

sakura 和 skr 是同一个入口的两个别名。Sakura 启动后会把当前工作目录作为工作区，所有文件分析和修改都限制在该工作区范围内。

选择终端前端

首次安装后的默认前端是 Sakura OpenTUI。它需要单独安装 Bun，Sakura 不会自动下载 Bun，也不会在缺少 Bun 时静默切换到 Pi TUI。

pnpm add -g @huskky/sakurai              # 使用 pnpm 的全局安装方式
brew install oven-sh/bun/bun             # macOS 示例
curl -fsSL https://bun.sh/install | bash # Linux 示例；执行前请先审阅安装脚本

可按以下方式选择前端或恢复会话：

sakura                             # 使用已保存的前端偏好（默认 Sakura TUI）
sakura --tui pi                    # 本次使用 Pi TUI，不需要 Bun
sakura --tui sakura --continue     # 本次使用 Sakura TUI，并恢复当前工作区最近会话
/tui pi                            # 在会话中保存 Pi TUI 偏好，下次启动生效

若 Sakura Runtime Host 异常退出，重启后可运行 sakura --tui sakura --continue；退出提示中的 sakura --session <sessionId> 也可恢复指定会话。/theme 的 20 套主题目前由 Pi TUI 呈现，在 Sakura TUI 中会明确提示切换到 sakura --tui pi，不会悄悄回退。

更新 Pi 依赖

在 Sakura 源码目录执行：

sakura updatepi
# 或
skr updatepi

该命令会把 pi-coding-agent、pi-ai 和 pi-tui 更新到各自的最新稳定版本，随后自动运行类型检查、构建和完整测试。为避免误改全局 npm 安装目录，命令要求 Sakura 使用带 pnpm-lock.yaml 的源码工作副本；从 npm 全局安装的 Sakura 不直接执行依赖更新。

从源码工作副本启动 Sakura 时，启动前会自动检查这三个 Pi 包；发现新版本会执行同样的更新和验证流程。版本检查无法访问 registry 时会继续使用当前版本；检测到更新但更新或验证失败时会停止启动。npm 全局安装没有可安全改写的锁文件，因此不会自动改写其依赖。启动阶段的 Pi 版本检查、更新步骤和 Pi 自身的版本/包更新提示不会写入 Sakura 的启动界面；更新失败时只显示一条 Sakura 错误并停止启动。手动执行 sakura updatepi 仍会保留完整输出。

第一次启动与配置隔离

Sakura 默认使用自己的目录：

~/.sakura/agent/

首次启动时，如果本机存在 Pi 配置，Sakura 会将以下文件复制一份作为初始配置：

settings.json
models.json
models-store.json
auth.json
keybindings.json

复制只在 Sakura 尚未初始化时发生。之后 Sakura 和 Pi 分开读写，不会把 Sakura 的模型、认证或主题设置写回 Pi。若需要更换目录，可设置：

export SAKURA_AGENT_DIR="$HOME/.config/sakura-agent"
sakura

环境变量文件

仓库提供 .env.example 作为环境变量模板，真实 .env 会被 Git 忽略。需要使用环境变量时，在 Sakura 项目目录执行：

cp .env.example .env
# 编辑 .env，填写搜索 Key 或 GitHub Token 等可选配置
set -a
source .env
set +a
# 然后进入需要分析的项目目录再启动 Sakura
cd /path/to/your/project
sakura

.env 只管理运行时环境变量；Provider、模型、认证和通过 CLI 首次联网配置的凭据仍由 Sakura 独立目录中的 models.json、auth.json、network.json 等文件管理。

也可以在会话中检查或显式迁移 Provider 配置：

/sakura-config status
/sakura-config validate
/sakura-config migrate <Pi agent 目录>

迁移会先校验源配置，默认不覆盖已经存在的 Sakura models.json。API Key、Token 和密码不应写进项目文件或 README。

Skills

Sakura 同时加载：

~/.agents/skills：共享 Agent Skills 目录。
~/.sakura/agent/skills：Sakura 专属 Skills 目录。

同名 Skill 以 Sakura 专属目录中的版本为准。首次启动会将 Pi 的 Skills 复制到 Sakura 专属目录；符号链接不会被复制。项目自身的扩展、Prompt、主题和上下文文件不会被隐式加载，以避免不可信仓库改变 Sakura 的工作流。

启动时不会把两个完整 Skills 目录交给 Pi 递归扫描，而是使用 ~/.sakura/agent/skills-index.json 和 ~/.sakura/agent/.skills-index/ 中的轻量缓存索引，只读取已知 Skill 的展示元数据。进入界面后 Sakura 才会检查已记录的 Skill 文件；只有发现新增、删除或修改时才重建索引并刷新当前会话。 Pi TUI 启动顶部默认只显示 Sakura 标识和已加载 Skills 数量；按 Ctrl+O 可展开/收起完整 Skills 名称列表。Pi 自身的启动横幅、更新日志和包更新提示默认隐藏。

代码结构

src/main.ts                       稳定的 CLI 转发入口
src/pi/                           Pi SDK、Runtime、TUI 和命令适配层
src/sakura/core/ports/             Sakura 宿主无关端口
src/sakura/runtime/                Sakura 配置、Provider 校验和系统提示
src/sakura/workflow/               需求、任务计划、状态持久化和安全策略
src/sakura/features/project-analysis/  项目扫描、符号和依赖分析
src/sakura/features/requirements/      需求模型、渲染和确认
src/sakura/features/review/            Diff、影响分析和回归检查
src/sakura/features/git/               受控 Git 准备、提交、推送、PR 和回滚
src/sakura/features/network/           Tavily 搜索和公开 URL 抓取
src/sakura/features/knowledge/         本地 RAG 索引、Embedding 和重排
src/sakura/features/memory/            项目记忆和用户记忆
src/sakura/features/session/            当前工作区会话查询

能力目录中的工具只依赖 src/sakura/core/ports/，由 src/pi/tool-adapter.ts 转换为 Pi 工具；因此未来可以替换 Agent Host 或 TUI，而不改动需求、Review、Git、RAG 等领域代码。详细启动链路、依赖方向和当前尚未解耦的 Pi 部分见 docs/architecture/sakura-architecture.md。

基本使用方式

直接用自然语言描述任务即可。例如：

请先阅读这个项目，告诉我它解决什么问题，并输出目录结构树。先不要修改代码。

Sakura 会先进行只读分析。涉及修改时，默认按以下顺序推进：

阅读项目
  → 拆解需求
  → 等待需求确认
  → 生成并确认任务计划
  → 同步 Git 并创建开发分支
  → 修改代码
  → Review 与回归检查
  → 确认提交
  → 确认推送
  → 可选：创建 PR、确认合并或回滚

需求拆解

Sakura 会把需求标成以下类型：

BUG-n：现有行为不符合预期。
FEATURE-n：新增用户或系统能力。
NFR-n：性能、安全、兼容性、可维护性等非功能要求。
Q-n：缺少信息或存在多种合理解释的问题。

图片中直接观察到的内容会和模型推断区分展示。信息不明确时，Sakura 会列出两到三个猜想，并请求你确认。需求重新提交后，旧确认自动失效。未确认需求、未确认计划或工作区未准备完成时，修改工具会被阻断。

项目理解与代码阅读

Agent 可以调用以下只读能力：

inspect_project：识别项目类型、包管理器、入口、命令、目录树和关键文件。
inspect_symbols：分析 TypeScript/JavaScript 的顶层符号、相对导入和有限的静态调用关系。
knowledge_index / knowledge_status / knowledge_search：建立和查询当前项目知识索引。
session_search / session_read：查询当前工作区的历史会话。

索引和会话查询都限制在当前规范化工作区，并返回来源路径和行号。检索结果只是候选上下文，仍需回到当前源码验证。

Multi-Agent（第一版）

Sakura 可以在一次主 Agent 工具调用中启动最多 6 个临时只读子任务，并以最多 3 路并发执行。固定角色为：

Scout：探索项目并收集证据。
Planner：需求确认后给出计划建议。
Reviewer：只审查启动时冻结的 Diff 快照。

子 Agent 使用彼此隔离的内存会话，只能调用 read、grep、find、ls、inspect_project、inspect_symbols，以及已启用时的本地 knowledge_search。它们不能写文件、运行 Shell、联网、批准工作流或继续委派。主 Agent 是第一版中唯一的实现者和决策者；批次活动期间，主会话中的代码、计划、Review、Git 和记忆写入也会被 durable lease 冻结，直到所有子会话结束。

自动调用使用 subagents 工具，依赖通过 dependsOn 构成 DAG。Pi TUI 在同一个工具块中流式更新所有任务行；Ctrl+O 展开模型、推理等级和用量，Esc 会取消活动批次。手动命令完成后以 nextTurn 消息写回当前会话，但不会自动触发主 Agent 回合：

/subagent scout "定位认证入口"
/subagent planner "给出实现步骤" --tier deep --model provider/model --thinking high

硬上限为：批次 300 秒；单结果 16 KiB；汇总结果 48 KiB；light/standard/deep 分别最多 4/8/12 回合、60/120/240 秒和 32k/96k/192k Token。子 Agent Token 计入 Provider 实际用量，但不会被并入主会话上下文；父会话只收到有大小上限的结构化摘要与证据。

角色档位映射保存在 Sakura 私有目录的 multi-agent.json。/sakura-agents status 会显示活动批次和 lease；进程异常退出后，遗留的 active lease 会在下次启动标为 stale。为避免误解冻另一个批次，只能用 /sakura-agents recover <完整 batchId> 显式恢复，子任务不会自动重放。当前只集成 Pi TUI；Sakura OpenTUI 不在这个基线版本的范围内。

交互命令

这些命令在 Sakura 会话中输入，命令名以 / 开头：

| 命令 | 用途 | | --- | --- | | /theme | 从 20 套内置主题中选择主题；当前仅由 Pi TUI 呈现。 | | /model | 使用 Pi 原生模型选择器；运行时仍读取 Sakura 的模型目录。 | | /tui pi 或 /tui sakura | 保存下一次启动使用的终端前端。 | | /sakura-model | 选择 Sakura 模型；也可写成 /sakura-model provider/model。 | | /sakura-routing | 查看或配置自动路由、备用模型和 manual/cost/quality/balanced 策略。 | | /sakura-config | 执行 status、validate 或 migrate <Pi agent 目录>。 | | /sakura-status | 查看需求版本、计划、Review、检查、Git、Provider 和当前模型。 | | /sakura-trace [runId] | 查看脱敏的结构化执行事件和最近检查点。 | | /sakura-resume [runId] | 从安全检查点恢复未完成任务；未确认修改不会自动重放。 | | /sakura-cancel [runId] | 取消活动任务并持久化取消状态。 | | /sakura-usage | 查看本次会话的 Token、费用、消息、工具调用和上下文占用。 | | /sakura-history | 搜索当前工作区会话；使用 /sakura-history read <sessionId> 回读时间线。 | | /subagent <role> <task> [overrides] | 手动运行一个只读 scout、planner 或 reviewer。 | | /sakura-agents status\|on\|off\|set\|clear\|recover | 查看、开关和配置 Multi-Agent，或显式恢复 stale lease。 |

启动时也可以直接恢复会话：

sakura --continue                         # 继续当前工作区最近的会话
sakura --session <sessionId>              # 打开指定会话
sakura --tui pi                           # 本次使用 Pi TUI
sakura --tui sakura --continue            # Sakura TUI 中继续最近会话

Sakura TUI 中可直接使用 /settings、/scoped-models、/session、/hotkeys、/changelog、/debug 和 /logout；/share 会在二次确认后创建私密 GitHub Gist。为避免 API Key 在终端中明文显示，/login 请使用 sakura --tui pi；Sakura 默认不加载项目本地资源，因此 /trust 不会改变当前安全策略。

主题包含 Sakura Blossom、Ink & Wash、Midnight Terminal、Cobalt Grid、Solarized Lab 等 20 套风格。预览文件见 docs/sakura-cli-theme-preview.html 和 docs/sakura-theme-gallery.html。

联网查询

搜索公开网页

web_search 使用 Tavily Search API，需要设置 Key：

export SAKURA_TAVILY_API_KEY="your-key"
sakura

也兼容 TAVILY_API_KEY。fetch_url 可以直接读取公开的 http:// 或 https:// URL，不需要搜索 Key。例如：

搜索 Node.js 22.19.0 的官方变更，并只引用官方来源。

如果没有预先配置搜索 Key，Sakura 会在首次触发 web_search 时暂停当前任务，显示 Tavily 官方申请入口和 API Key 控制台，并在 CLI 中询问是否输入 Key。输入后会保存到 Sakura 私有配置目录的 network.json（默认 ~/.sakura/agent/network.json），不会写入项目文件或普通聊天消息；保存成功后会自动重试当前搜索。非交互模式仍需通过环境变量提供 Key。

官方入口：Tavily，API Keys 控制台。

网络工具是只读的。Sakura 会限制请求大小、响应时间和可访问地址，拒绝本地地址、内网地址、凭据嵌入 URL 和非公开文件读取。

单次 Agent Loop 默认最多运行 40 回合或 10 分钟，可用以下环境变量调整：

export SAKURA_MAX_TURNS=60
export SAKURA_MAX_DURATION_MS=900000

本地 RAG 与记忆

项目知识索引

知识索引默认保存在：

~/.sakura/agent/knowledge/

在会话中让 Sakura 建立或更新索引：

请建立或增量更新当前项目的知识索引，然后搜索和认证配置相关的源码。

索引会跳过依赖、构建产物、敏感配置和不在允许范围内的文件；文件按 hash 增量更新，删除的文件会清理对应片段。未配置 Embedding 时使用关键词检索。

可选 Embedding

在 ~/.sakura/agent/knowledge.json 中配置一个已经存在于 Sakura models.json 的 Embedding 模型：

{
  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "dimensions": 1536,
    "batchSize": 32
  }
}

Embedding 只引用 Sakura 自己的 Provider 和认证配置，不在 knowledge.json 中保存密钥。配置缺失、认证失败、网络失败或向量维度不一致时，会明确回退到关键词检索，不会阻断项目分析。可选向量保存在 Sakura 的 knowledge/ 目录，目前不依赖独立向量数据库。

项目记忆与用户记忆

项目记忆按工作区隔离，默认保存为：

~/.sakura/agent/memory/<workspace-hash>.json

用户记忆独立保存为：

~/.sakura/agent/memory/user.json

保存或删除记忆必须由用户明确请求或确认，且会拒绝 API Key、Token、密码、私钥等敏感内容。记忆是辅助上下文，不替代当前用户指令、源码验证、Review 或测试。

Code Review 与回归检查

代码修改完成后，Sakura 会读取开发分支相对基线的完整 Diff，包括已跟踪和未跟踪文件。review_changes 当前提供以下静态候选提示：

凭据字面量。
eval 等高风险调用。
显式 any。
调试输出。
新增行的文件位置、严重级别、原因、影响和建议。

这些提示需要 Agent 结合上下文复核。run_checks 还会比较 Git 基线和当前 TypeScript/JavaScript AST，识别导出符号移除、公共函数/方法/类型签名变化和新增导出，并把受影响的调用方文件与测试写入语义证据；高风险语义变化、配置、入口或未知变更会升级为完整检查。动态 import、动态 require 或语法解析不完整时会标记低置信度并提示人工确认。失败会按类型、断言、Lint、超时或环境问题给出诊断。submit_review 会持久化报告，未解决问题会触发硬门禁。

因此，Review 通过不等于“代码一定正确”，而是表示当前变更已完成 Sakura 能执行的检查，并且结果已经展示给用户。

Git 交付闭环

准备工作区

Sakura 只在已确认需求和计划后准备 Git：

定位仓库根目录和默认分支。
检查本地是否干净、是否处于 detached HEAD、是否存在远端。
fetch 远端并执行 pull --ff-only。
创建 sakura/fix/*、sakura/feat/* 或 sakura/task/* 开发分支。

已有未提交修改、无法快进、分支冲突或远端状态不明确时会暂停，不会自动 stash、reset、rebase、清理文件或覆盖修改。

提交与推送确认

提交前会先展示文件和 Diff 统计。只有用户输入以下确认词后，Sakura 才会执行对应操作：

确认提交
确认推送
确认创建 PR
确认合并
确认回滚

commit、push、创建 PR、合并和回滚是相互独立的授权。禁止 force push。Git 状态或变更发生变化后，旧的确认和 Review 会失效。

Git 工具包括：prepare_git_workspace、git_status、git_commit_preview、git_commit、git_push、git_create_pr、git_merge_pr 和 git_rollback。GitHub PR 操作需要配置 SAKURA_GITHUB_TOKEN、GITHUB_TOKEN 或 GH_TOKEN。

配置与数据目录

~/.sakura/
├── agent/
│   ├── auth.json                 # Sakura 独立认证配置
│   ├── models.json               # Provider 与模型目录
│   ├── settings.json             # 主题、当前模型等设置
│   ├── network.json              # Sakura 联网工具凭据（私有）
│   ├── routing.json              # 自动路由策略
│   ├── multi-agent.json          # 子 Agent 角色、模型和推理等级映射
│   ├── knowledge.json            # 可选 Embedding 配置
│   ├── skills/                   # Sakura 专属 Skills
│   ├── knowledge/                # 项目知识索引和向量
│   ├── memory/                   # 项目/用户记忆
│   ├── runs/                     # 脱敏 Trace、任务摘要和检查点
│   ├── multi-agent-runs/         # 按工作区隔离的子批次 JSONL Trace
│   └── sessions/                 # 按工作区隔离的会话
└── tasks/
    └── <workspace-hash>.json     # 需求、计划、Review、Git 状态

Sakura 会给配置和记忆目录设置较严格的权限，并对写入内容做敏感信息检查。不要把 ~/.sakura/agent 提交到项目仓库。

项目结构

sakura/
├── bin/sakura.js                 # npm 全局命令入口
├── src/
│   ├── main.ts                   # 稳定的 CLI 转发入口
│   ├── pi/                       # Pi SDK、Runtime、TUI 和命令适配层
│   └── sakura/                   # Sakura 宿主无关业务层
│       ├── core/ports/           # 工具和宿主能力契约
│       ├── runtime/              # 配置、Provider 校验和系统提示
│       ├── tui/                  # 可替换前端协议、Node Runtime Host 与 OpenTUI
│       ├── workflow/             # Agent Loop 门禁、计划和状态协调
│       └── features/             # 项目分析、需求、Review、Git、RAG、记忆、会话和联网
├── themes/                       # 20 套 Sakura CLI 主题
├── test/                         # Node 与 OpenTUI 自动化测试
├── docs/                         # 能力路线、设计规格和主题预览
└── scripts/                      # 打包与 macOS/Linux PTY 冒烟测试

开发与验证

在项目根目录执行：

pnpm install
pnpm check          # TypeScript 类型检查
pnpm test           # 自动化测试
pnpm build          # 生成 dist
pnpm test:tui       # Bun/OpenTUI 组件与交互测试
pnpm test:tui:pty   # 真实 PTY 启动、退出和恢复命令冒烟测试（macOS/Linux）
pnpm test:package   # 打包、安装、sakura/skr 别名和主题资源冒烟测试
git diff --check    # 检查空白和冲突标记

发布前至少应通过类型检查、自动化测试、构建、OpenTUI PTY 和包冒烟测试。CI 会在 macOS 与 Linux 上执行同一组 OpenTUI 检查。只修改文档时也建议运行 pnpm check 与 pnpm test:package，避免 README 中的安装命令与实际包结构漂移。

当前能力与后续计划

已落地的核心能力包括：

Pi SDK 驱动的中文交互式 Coding Agent。
可选 Sakura OpenTUI 与 Pi TUI：Sakura OpenTUI 使用独立 Bun 前端和 Node Runtime Host，Pi Agent Loop 仍负责模型与工具执行。
需求拆解、用户确认、结构化计划、里程碑和依赖门禁。
项目结构树、符号索引、受控文件修改和 Bash 工具。
Diff Review、AST 语义变化识别、影响分析、回归测试选择、失败诊断和报告持久化。
独立 Provider/模型配置、手动切换、自动路由和用量统计。
脱敏结构化 Trace、任务检查点、Trace 查看、任务恢复和取消命令。
只读联网搜索、公开 URL 抓取、项目知识索引、项目记忆、用户记忆和会话历史。
开发分支、pull、commit、push、PR、合并和回滚的确认门禁。
20 套 CLI 主题，以及共享 Skills 和 Sakura 专属 Skills 隔离加载。
固定 Scout/Planner/Reviewer 的只读 Multi-Agent DAG、并发调度、Pi TUI 流式状态和 durable mutation lease。

仍在路线图中的主要能力：

Implementer 子 Agent、可写工作树隔离与 Sakura OpenTUI 的 Multi-Agent 展示。
LSP、动态调用链、类型系统级 AST 语义 Review 和更精确的失败归因。
Provider 交互式编辑、JSONC 完整兼容、费用预算、延迟和成功率指标。
完整会话语义检索、自动记忆抽取、独立向量数据库和远程重排。
Git 冲突辅助解决、完整回滚 PR、自动变更日志、评测集和服务化部署。

详细完成情况和后续验收标准见 docs/sakura-agent-capability-outline.md，初始设计见 docs/superpowers/specs/2026-07-30-sakura-coding-agent-design.md。

许可证与贡献

当前 package.json 将 Sakura 标记为私有包，仓库尚未声明公开许可证或 npm 发布流程。提交代码前请遵循需求确认、Review、验证和 Git 分阶段确认流程；不要直接向主分支推送。