内容
# Shaka
Shaka 是一个本地的、与供应商无关的框架，用于塑造 AI 编程助手的工作方式。它为 Claude Code、Codex、opencode 和 Pi 等助手添加了共享上下文、可重用的技能和命令、工作流自动化、内存搜索、MCP 工具和安全钩子。目标是给您已经使用的助手相同的指令、工具定义、内存和防护措施。
它适用于使用 AI 助手进行实际项目的开发人员，并希望这些助手记住偏好、遵循可重复的工作流、重用特定于项目的指导并避免不安全的命令。没有像 Shaka 这样的层，每个供应商往往有自己的配置、历史、命令和安全模型；切换工具意味着丢失上下文或重建相同的约定。
AI 辅助开发依赖于除模型之外的更多因素。周围的运行时环境决定了注入什么上下文、助手可以调用哪些工具代码、如何验证命令以及如何找到过去的工作。Shaka 将这些部分保留在本地、可检查并由您拥有。
Shaka 围绕几个具体部分组织：
- **MCP 工具** 通过 MCP 将 Shaka 工具暴露给支持的供应商。
- **钩子** 在会话和工具事件上运行，在会话开始时加载上下文，在会话结束时写入内存，并在执行前验证工具使用。
- **技能** 是用于重复任务、领域和操作样式的基于 Markdown 的攻略。
- **工作流** 将命令、提示和 shell 步骤链接成可重复的多步骤过程。
- **内存搜索** 查询存储的会话摘要、主动学习和存档学习，以便未来会话可以在不重读每个记录的情况下恢复有用的上下文。
- **命令安全验证** 在执行前将匹配的 bash 命令和文件路径与安全模式进行比较。
## 入门指南
```bash
git clone https://github.com/jgmontoya/shaka.git
cd shaka
bun install
bun link
shaka init
```
`shaka init` 将检测您已安装的供应商（Claude Code、opencode、Codex、Pi 或任意组合）并设置一切。
**先决条件：** [Bun](https://bun.sh) （确保它在您的 `PATH` 上） 和 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[opencode](https://opencode.ai)、[Codex](https://github.com/openai/codex) 或 [Pi](https://pi.dev) 中的至少一个。
安装后，最快的检查命令是：
```bash
shaka doctor # 检查安装健康状况
shaka commands list # 查看可用命令
shaka skill list # 查看系统和已安装的技能
shaka memory search "query" # 搜索摘要和学习内容
shaka mcp serve # 为支持的供应商启动 MCP 服务器
```
对于源代码开发，请运行：
```bash
bun install
just check
bun run src/index.ts --help
```
## 工作原理
在 `shaka init` 之后，Shaka 通过供应商钩子工作：
1. **您启动一个会话** （Claude Code、opencode、Codex 或 Pi）。`session-start` 钩子将推理框架、已编辑的顶级用户文件、选定的学习内容、项目知识索引、汇总和最近的会话摘要加载到对话上下文中。
2. **您正常工作。** 输入提示、提问、编写代码。Shaka 是透明的。
3. **AI 尝试运行命令。** `security-validator` 钩子拦截它，根据您的安全模式检查命令并在执行前阻止任何灾难性的命令。
4. **您想要自定义。** 将 `system/` 中的任何文件复制到 `customizations/` 并编辑它。您的版本具有更高的优先级。升级永远不会触及您的文件。
就是这样。没有单独的聊天 UI 需要学习；日常界面仍然在您现有的助手内部。
## 哲学
灵感来自 [PAI](https://github.com/danielmiessler/Personal_AI_Infrastructure)、[Ren](https://github.com/erskingardner/ren) 和 [openclaw](https://github.com/openclaw/openclaw)，但专注于：
1. **确定性优先** — 在涉及模型之前，尽可能在代码中完成。
2. **本地优先** — 无遥测，无必需的云服务，与本地模型一起工作。
3. **增量** — 在每个阶段交付可用的软件。
4. **可扩展** — 轻松添加工具、技能和代理。
5. **清晰的边界** — 模板与用户文件永远不会混淆。
## 架构
### 设计原则
1. **Bun 是已承诺的运行时** -- 没有围绕 Bun API 的抽象层。服务直接使用 `Bun.file()`、`Bun.spawn()` 等。
2. **钩子是独立的脚本** -- 直接用 `bun` 运行，不需要在运行时需要 CLI 二进制文件。
3. **内容是声明式的** -- Markdown 文件、JSON 配置、YAML 模式。只有在需要确定性时才使用代码。
4. **根级依赖** -- `defaults/` 是纯内容。里面没有 `node_modules/`。
5. **所有供应商都是首要的** -- Claude Code、opencode、Codex 和 Pi 都得到相同的待遇，没有一个主要 + 其他作为事后补充。
有关关键结构决策的理由，请参阅 [架构决策](docs/architecture-decisions.md)。
### 目录结构
```text
~/.config/shaka/ # XDG-compliant, 供应商无关
├── user/ # 您的内容（可移植，已备份）
│ ├── user.md # 您是谁（姓名，时区，句柄）
│ ├── assistant.md # 您的助手如何表现
│ ├── missions.md # 高级目标（TELOS-lite）
│ ├── goals.md # 具体目标
│ ├── projects.md # 活跃项目和路径
│ ├── tech-stack.md # 首选技术
│ └── <your-folders>/ # 子目录不会自动加载
│ └── ...
│
├── memory/ # Shaka 关于您的学习内容（动态）
│ └── ... # 摘要、学习内容、汇总、安全日志
│
├── customizations/ # 您对 system/ 的覆盖
│ ├── base-reasoning-framework.md # （示例）您的推理变体
│ └── hooks/ # 您的钩子
│
├── skills/ # 已安装的第三方技能（通过 `shaka skill install`）
│
├── skills.json # 跟踪已安装的技能（源，供应商，版本）
│
├── system/ → <repo>/defaults/system # 框架的符号链接（在升级时替换）
│ ├── base-reasoning-framework.md # 默认推理框架
│ ├── hooks/ # 事件驱动的自动化
│ ├── commands/ # 斜杠命令（Markdown）
│ ├── workflows/ # 多步骤管道（YAML）
│ ├── skills/ # 可重复使用的攻略（Markdown）
│ ├── tools/ # 向供应商公开的操作
│ └── agents/ # 专门的角色（Markdown）
│
└── config.json # 配置文件
```
> **用户文件加载：** 直接在 `user/` 下编辑的 `.md` 文件会在会话开始时注入到 AI 的上下文中；未更改的默认模板将被跳过。 **保持此级别精简** — 仅保留对每个会话都有用的文件，例如配置文件、助手行为、任务、目标、活跃项目和技术栈。对于详细参考资料（样式指南、API 文档、项目特定信息），请创建子目录。子目录文件 **不会** 自动加载 — 模型可以按需读取它们，当相关时。
> **索引模式：** 如果您添加子目录，请创建 `user/index.md` 以帮助模型发现它们。由于它位于顶级，因此它会自动加载并充当路由指南：
>
> ```markdown
> # 用户上下文索引
>
> ## reference/
>
> 详细的样式指南和编码约定。在做出样式或格式决策时阅读。
>
> ## api-docs/
>
> 内部 API 文档。在集成或构建我们的服务时阅读。
> ```
### 关键原则：关注点分离
| 目录 | 目的 | 所有者 | 升级 | 备份 |
| ----------------- | --------------------------------- | ----- | ----------------- | ------ |
| `user/` | 您是谁（您编写） | 您 | 永远不会触及 | 是 |
| `memory/` | Shaka 学到了什么（Shaka 编写） | Shaka | 永远不会触及 | 是 |
| `customizations/` | 您对 system/ 的覆盖 | 您 | 永远不会触及 | 是 |
| `skills/` | 已安装的第三方技能 | 您 | 永远不会触及 | 是 |
| `config.json` | Shaka 设置和供应商偏好 | 您 | 不会被覆盖 | 是 |
| `system/` | 框架默认值（符号链接） | Shaka | 完全替换 | 否 |
当 Shaka 升级时，`system/` 会重新链接到新版本。其他所有内容都保留。
### 自定义覆盖
`customizations/` 中的文件会覆盖其对应的 `system/` 文件：
```text
customizations/base-reasoning-framework.md → 覆盖 → system/base-reasoning-framework.md
customizations/hooks/session-start.ts → 覆盖 → system/hooks/session-start.ts
customizations/tools/foo.ts → 覆盖 → system/tools/foo.ts
```
**解析顺序：** 自定义 → 系统默认
这允许您调整推理框架、添加钩子或替换工具，而无需修改 `system/`。您的自定义在升级过程中存活下来。
## 命令行界面
### 可用命令
```bash
shaka init # 设置 Shaka（创建目录、符号链接、安装钩子）
shaka init --claude # 仅为 Claude Code 设置
shaka init --opencode # 仅为 opencode 设置
shaka init --codex # 仅为 Codex 设置
shaka init --pi # 仅为 Pi 设置
shaka init --all # 为所有检测到的供应商设置
shaka update # 升级到最新版本（基于标签）
shaka uninstall # 删除钩子和框架链接；保留用户数据
shaka reload # 重新发现钩子并重新生成供应商配置
shaka doctor # 检查安装健康状况
shaka mcp serve # 启动 MCP 服务器（用于 Claude Code/Codex 工具集成）
shaka commands list # 显示所有命令和状态
shaka commands new <name> # 创建新命令
shaka commands disable <name> # 禁用命令
shaka commands enable <name> # 重新启用已禁用的命令
shaka skill install <source> # 安装技能（自动检测 GitHub 或 Clawhub）
shaka skill remove <name> # 删除已安装的技能
shaka skill update [name] # 更新一个或所有已安装的技能
shaka skill list # 列出系统 + 已安装的技能
shaka run <workflow> [input...] # 执行多步骤工作流
shaka scan <file> # 扫描散文的 AI 编写模式（slop）
shaka scan --dir <path> # 扫描目录中的所有 `.md` 文件
shaka memory search <query> # 搜索会话摘要和学习内容
shaka memory stats # 显示学习内容计数、曝光和类别分解
shaka memory review # 交互式浏览和管理学习内容
shaka memory review --prune # AI 辅助学习内容质量评估
shaka memory consolidate # 消除重复、解决矛盾并压缩相关学习内容
shaka memory compile # 将会话知识编译成主题页面
```
### 初始化流程
`shaka init` 执行以下操作：
1. 检测已安装的供应商（Claude Code、opencode、Codex、Pi）
2. 提示选择供应商（或使用 `--claude`/`--opencode`/`--codex`/`--pi`/`--all`）
3. 创建 `user/`、`memory/`、`customizations/` 目录
4. 将 `system/` 符号链接到存储库的 `defaults/system/`
5. 复制用户文件模板 (`user.md`、`assistant.md`、`missions.md`、`goals.md`、`projects.md`、`tech-stack.md`)
6. 通过 `bun link` 在全局范围内注册 `shaka` 包
7. 为选定的供应商安装钩子
8. 在 `.shaka-version` 中跟踪版本
### 升级流程
`shaka update` 使用 git 标签进行发布：
1. 从远程获取最新的标签
2. 比较当前版本和最新版本
3. 在主版本更新时发出警告并提示
4. 检出新标签并重新运行 init
## 基本推理框架
Shaka 使用受 [PAI 算法](https://github.com/danielmiessler/TheAlgorithm) 启发的结构化推理框架，在会话开始时加载。默认框架要求 AI 执行 7 个阶段 — OBSERVE、THINK、PLAN、BUILD、EXECUTE、VERIFY、LEARN — 并在采取行动前定义可测试的成功标准（ISC）。
要自定义，请将 `system/base-reasoning-framework.md` 复制到 `customizations/` 并编辑。有关详细信息，请参阅 [推理框架](docs/reasoning-framework.md)。
## 核心概念
Shaka 使用 **渐进抽象模型**，其中每一层都建立在前一层之上：
```text
┌─────────────────────────────────────────────────────────────────────────┐
│ 工作流 │ 多步骤管道，具有隔离的上下文 │
│ │ 链接命令、提示和脚本 │
│ │ 例如，review-and-fix、plan-feature │
├──────────────┼──────────────────────────────────────────────────────────┤
│ 技能 │ 领域专业知识和上下文容器 │
│ │ 文件夹包含 SKILL.md + 可选支持文件 │
│ │ 例如，tdd/、writing-rules/ │
├──────────────┼──────────────────────────────────────────────────────────┤
│ 命令 │ 单用途提示模板 │
│ │ 供应商调用的提示模板 │
│ │ 例如，/code-review │
├──────────────┼──────────────────────────────────────────────────────────┤
│ 工具 │ 通过 MCP/本地桥接公开的 TypeScript 操作 │
│ │ 可能会运行本地代码或桥接到供应商 CLI │
│ │ 例如，inference.ts │
└──────────────┴──────────────────────────────────────────────────────────┘
```
### 工具
TypeScript 模块，公开可调用的操作给助手。一些工具是确定性代码；其他工具（如 `inference.ts`）桥接到 AI 供应商 CLI。
目前，Shaka 随附两个工具：
- **`inference.ts`** — 供应商无关的 AI 推理（包装 Claude CLI、opencode CLI、Codex CLI 或 Pi CLI）
- **`memory-search.ts`** — 搜索会话摘要和学习内容按关键字
两个工具都通过 Shaka 的 MCP 服务器（`shaka mcp serve`）公开给每个支持的供应商的模型：Claude Code 和 Codex，通过 Shaka 的 MCP 服务器（`shaka mcp serve`），opencode 通过生成的插件的 `tool` 字段，Pi 通过 `pi.registerTool()` 在生成的扩展中。生成的 opencode 和 Pi 桥接器外壳会调用 `shaka tool <name>`，当这些工具运行时，而 MCP 供应商通过 MCP 服务器执行相同的工具定义。工具定义位于一个位置（`defaults/system/tools/`），无论模型运行在哪个供应商下。
工具是 TypeScript 文件，导出具有 `description`、`inputSchema` 和 `execute` 的工具定义：
```typescript
// 示例：~/.config/shaka/system/tools/my-tool.ts
export default {
name: "my-tool",
description: "描述工具的作用",
inputSchema: {
type: "object",
properties: {},
},
async execute(args) {
return "result";
},
};
```
工具通过以下方式公开给 AI 供应商：
- **Claude Code**：通过 `shaka mcp serve` （MCP 服务器）
- **Codex**：通过 `shaka mcp serve` （MCP 服务器）
- **opencode**：作为生成的 Shaka 插件中的原生工具公开
- **Pi**：通过 `pi.registerTool()` 在生成的扩展中公开（原生）
### 命令
原子命令提示模板。命令提供元数据和提示正文，然后由提供者让模型以正常的工具访问作出回应。命令文件是带有 YAML 前置信息的 Markdown。
```markdown
---
description: 创建带有 AI 生成的消息的 git 提交
subtask: false
cwd:
- "*"
providers:
claude:
model: sonnet
opencode:
model: openrouter/anthropic/claude-sonnet-4.6
---
检查工作树中的更改，然后生成一个符合约定的提交消息。
$ARGUMENTS
```
**前置信息字段：**
| 字段 | 是否必需 | 描述 |
| ---------------- | -------- | -------------------------------------------------------------------------- |
| `description` | 是 | 提供者命令 UI 中显示的简短描述 |
| `argument-hint` | 否 | 命令名称后显示的提示（例如， `[branch\|#pr]`） |
| `subtask` | 否 | 作为后台子代理（`true`）或内联（`false`，默认）运行 |
| `model` | 否 | 覆盖默认模型 |
| `user-invocable` | 否 | 在提供者命令 UI 中显示（`true`，默认）或隐藏用于内部使用 |
| `cwd` | 否 | 作用域安装的项目路径。 `["*"]` = 全局（与省略相同） |
| `providers` | 否 | 提供者特定字段覆盖（例如，claude/opencode 的不同 `model`） |
**正文替换：** Shaka 处理 `$ARGUMENTS`（所有参数）和 `$1`/`$2`/...（位置参数）。提供者原生 shell 块（例如 `` !`cmd` ``）在提供者支持时保留。
命令是主要的提示模板接口。提供者通过其原生命令、技能或提示机制来展现它们。
**预装命令：**
| 命令 | 用途 |
| ------------- | --------------------------------------- |
| `code-review` | 审查本地更改、分支或 PR |
命令位于 `system/commands/`（预装）和 `customizations/commands/`（用户）。自定义命令通过文件名匹配覆盖系统命令。
```bash
shaka commands list # 显示所有命令和状态
shaka commands new <name> # 创建新命令
shaka commands disable <name> # 禁用命令
shaka commands enable <name> # 重新启用已禁用的命令
```
### 工作流
多步骤管道，链接命令、提示和 shell 脚本。每个步骤都运行在全新的 AI 环境中，通过文件系统和模板变量进行通信 — 防止在一次长对话中试图完成所有事情时出现的上下文退化。
```yaml
# review-and-fix.yaml
description: 审查代码更改并修复发现的问题
steps:
- name: review
command: /code-review
- name: fix
prompt: |
读取 reviews/review.md 中的代码审查。
修复有效问题，跳过错误建议。
完成后删除 reviews/。
```
**步骤类型：**
| 类型 | 描述 | 示例 |
| --------- | --------------------------------------------- | ------------------------------- |
| `command` | 通过提供者调用 Shaka 命令 | `command: /code-review` |
| `prompt` | 带有完全工具访问权限的内联 AI 指令 | `prompt: Fix the failing tests` |
| `run` | Shell 脚本（无 AI，无令牌） | `run: bun test` |
**模板变量** 用于在步骤之间传递数据：
| 变量 | 描述 |
| ------------------------- | ---------------------------------------------------------- |
| `{input}` | CLI 输入（`shaka run workflow "this text"`） |
| `{previous.output}` | 上一步的 stdout（跨迭代传递） |
| `{previous.exitCode}` | 上一步的退出代码（跨迭代传递） |
| `{steps.<name>.output}` | 命名步骤的 stdout（当前迭代） |
| `{steps.<name>.exitCode}` | 命名步骤的退出代码（当前迭代） |
| `{loop.iteration}` | 当前循环迭代（基于 1） |
| `{loop.total}` | 配置的循环次数 |
**循环：** 添加 `loop: N` 以重复所有步骤 N 次。对于测试-修复循环等迭代细化模式非常有用。每次迭代的工件都存储在 `iter-N/` 子目录中。在 CLI 上使用 `--loop N` 以覆盖。
**分组步骤：** 内联组在单个名称下组成多个步骤，具有可选的循环：
```yaml
steps:
- name: refine
loop: 3
steps:
- name: critique
prompt: 批判性地审查计划
- name: revise
prompt: 解决有效反馈
```
组隔离它们的 `{steps.<name>}` 范围 — 内部步骤无法看到外部变量，而外部工作流通过 `{steps.refine.output}` 看到组的最后一个结果。
**工作流引用：** 重用整个工作流作为一步。被引用的工作流的步骤内联为一个组，继承其循环次数：
```yaml
steps:
- name: setup
run: echo "preparing"
- name: review-cycle
workflow: review-and-fix
- name: deploy
run: echo "deploying"
```
引用在检测到循环后以传递方式解析。
**Git 状态管理：** 默认情况下（`state: "git-branch"`），运行器在分支上创建一个临时工作树，在产生更改的每个步骤后提交，并在失败时停止。使用 `state: "none"` 进行仅分析工作流。
**错误处理：** 默认情况下，步骤在非零退出时失败（快速失败）。将步骤标记为 `allow-failure: true` 以继续执行 — 对于输出馈送到下一个 AI 步骤的测试步骤非常有用。
工作流位于 `system/workflows/`（预装）和 `customizations/workflows/`（用户）。自定义工作流通过文件名匹配覆盖系统工作流。
**预装工作流：**
| 工作流 | 用途 |
| ---------------- | ---------------------------------------------------------- |
| `review-and-fix` | 运行代码审查，然后评估和修复有效问题 |
| `plan-feature` | 使用迭代批评和修订循环规划功能 |
```bash
shaka run review-and-fix # 运行预装的 review-and-fix 工作流
shaka run my-workflow "input" # 使用输入运行自定义工作流
```
### 技能
复杂工作流的领域容器。技能是带有 `SKILL.md` 和可选支持文件的**文件夹**。技能以 Markdown 为主：它们为 AI 提供上下文和工作流指导，安装的技能在链接到提供者目录之前会扫描。
**预装技能：**
| 技能 | 用途 |
| ------------------ | --------------------------------------------------------- |
| autoresearch | 假设、基准测试、保留/丢弃优化协议 |
| autoresearch-setup | `shaka autoresearch start` 的基准测试环境设置 |
| be-creative | 扩展思考和多样化选项生成 |
| council | 多视角辩论（3-7 个代理） |
| experiment | 可重复的验证概念验证 |
| first-principles | 分解、挑战和重建推理 |
| red-team | 对抗性验证（32 个代理） |
| science | 科学方法工作流 |
| tdd | 测试驱动开发（实现工作的默认设置） |
| validate-plan | 实施前进行多轮压力测试 |
| writing-rules | 防错写作约束加上 `shaka scan` |
技能由上下文调用（“审查此 PR”）或显式调用（“使用代码审查技能”）。
**安装技能：**
技能可以从 GitHub 仓库或 Clawhub 注册表安装。根据输入格式自动检测源：
```bash
# GitHub（自动检测输入中包含 /）
shaka skill install user/repo # 简写
shaka skill install user/repo#v1.0.0 # 特定引用
shaka skill install https://github.com/user/skill-repo
shaka skill install https://github.com/user/repo/tree/main/skills/my-skill
# Clawhub（自动检测为不含 / 的裸词）
shaka skill install sonoscli # 最新版本
shaka skill install sonoscli@1.2.0 # 特定版本
# 显式提供者覆盖
shaka skill install my-skill --github # 强制 GitHub 提供者
shaka skill install my-skill --clawhub # 强制 Clawhub 提供者
shaka skill install my-skill --clawdhub # 旧别名（已弃用）
# 安全选项
shaka skill install user/repo --yolo # 跳过安全检查和提示
```
没有根 `SKILL.md` 的 GitHub 仓库通过备用路径发现：市场元数据（`.claude-plugin/marketplace.json`）、Claude 布局（`.claude/skills/<name>/SKILL.md`）和插件样式 `skills/<name>/SKILL.md`。
已安装的技能位于 `skills/` 并符号链接到启用的提供者技能目录。安全扫描在安装前会标记可执行文件和未知文件类型（`.ts`、`.js`、`.sh` 等）、URL、HTML 注释和不可见字符。
### 代理
定义为 Markdown 提示模板的专用角色。每个代理都有一个定义的角色、工具访问限制和行为准则。
**17 个代理定义随 Shaka 交付：** Algorithm、Architect、Artist、ClaudeResearcher、CodeReviewer、CodexResearcher、Designer、DevOpsEngineer、Engineer、GeminiResearcher、GrokResearcher、Intern、Pentester、QATester、TechnicalWriter，以及 Shaka 自身使用的内部 `autoresearch-setup` 和 `inference` 代理。
```markdown
---
name: reviewer
description: 代码审查专家（只读）
capability: review
permissions:
allow:
- "Read(*)"
- "Grep(*)"
- "Glob(*)"
mode: subagent
permission:
read: allow
grep: allow
glob: allow
---
您是代码审查员。您分析代码但从不修改它。
```
### 钩子
事件驱动的自动化。运行在特定事件上的 TypeScript 脚本。
**预装钩子：**
| 钩子 | 事件 | 它所做的事情 |
| ----------------------- | --------------- | ----------------------------------------------------------------- |
| `session-start.ts` | `session.start` | 加载推理框架、用户上下文、最近的会话摘要 |
| `session-end.ts` | `session.end` | 解析转录并生成会话摘要以备存储 |
| `security-validator.ts` | `tool.before` | 验证 bash 命令和文件路径是否符合安全模式 |
| `format-reminder.ts` | `prompt.submit` | 提醒 AI 遵循推理框架格式 |
**支持的事件：**
| 事件 | 触发 |
| --------------- | ----------------------- |
| `session.start` | 新对话开始 |
| `session.end` | 对话结束 |
| `tool.before` | 工具执行前 |
| `tool.after` | 工具执行后 |
| `prompt.submit` | 用户发送消息 |
这些是 Shaka 的规范钩子事件。提供者适配器将它们映射到原生提供者事件；例如，Codex 在内部使用其原生 `Stop` 事件处理 `session.end`。
### 记忆
持久上下文，生存期跨越会话。记忆系统捕获每个会话中发生的事情，以便 AI 可以引用过去的工作。
- **会话总结** — `session-end` 钩子解析转录（Claude Code JSONL、opencode 导出 JSON、Codex JSONL 或 Pi JSONL）并使用 AI 推理生成结构化摘要
- **摘要存储** —摘要存储为带有 YAML 前置信息的 Markdown，位于 `memory/sessions/`
- **会话上下文** — `session-start` 钩子将最近的摘要加载到上下文中，以便 AI 知道您最近的工作内容
- **滚动摘要** — 每天、每周和每月的汇总压缩会话历史记录成持久的逐项目摘要，在会话开始时加载到上下文中
- **搜索** — `shaka memory search <query>` 搜索摘要、活动学习和存档学习；也可以作为 MCP 工具在会话中搜索
- **知识编译** — `shaka memory compile` 从会话摘要中提取可重用的项目知识，生成主题页面和可加载的索引
- **审查** — `shaka memory review` 提供一个交互式 TUI，用于浏览、过滤和删除学习内容。 `--prune` 添加 AI 辅助质量评分，以标记低价值条目
- **合并** — `shaka memory consolidate` 运行三个步骤：重复数据删除、矛盾解决和凝聚。凝聚将相关的高曝光学习内容合并成复合条目，释放上下文预算。源条目被存档（可搜索、可恢复）
- **自动维护** — 每次会话后，系统检查时间（24 小时）和容量（10+ 条新学习内容）门槛。当触发时，它运行合并、自动提升跨项目学习内容到全局范围，并根据预算压力有条件地修剪质量最低的条目（上限为每次运行 3 个，安全地板为暴露和年龄）。可通过 `memory.maintenance.enabled` 配置
**计划：** 通过向量搜索（可能是 sqlite-vec）进行语义检索。
## 自动研究
自动研究是一种有状态的优化循环：代理提出更改，脚本基准测试测量更改，赢家提交，输家恢复，追加日志在上下文重置后累积。“研究”是一种算法研究：假设、测试、保留或丢弃 — 而不是网络研究。灵感来自 [Shopify 的 Autoresearch 文章](https://shopify.engineering/autoresearch)。
```bash
shaka optimize start "将 bun test 从 45 秒缩短到 <20 秒"
shaka optimize status
shaka optimize resume # 继续唯一的活动实验
shaka optimize resume <slug> # 从任何地方继续特定的实验
shaka optimize html <slug> # 生成并打开单个页面的 HTML 报告
shaka optimize cleanup <slug> # 删除实验工作树，可选地删除分支
```
`shaka autoresearch ...` 作为原始命令拼写仍然可用。`optimize` 是更友好的别名。
`start` 创建一个专用 git 工作树 + 分支（`autoresearch/<slug>`），因此循环永远不会触及您的主检出。每次迭代都会将代理组装成来自技能协议、`autoresearch.md` 规范和最近几条 jsonl 条目的提示，然后执行 `./autoresearch.sh` 进行测量。运行者在指标改善时提交，否则恢复，并在 `autoresearch.jsonl` 中追加一条 JSON 行（在运行程序提交中排除；保留跨恢复）。基准存储在 `autoresearch.meta.json` 中，以便报告和恢复可以区分原始基准和候选迭代。
`cleanup` 默认情况下是交互式的，并显示它将删除的内容，然后再删除任何内容。使用 `shaka optimize cleanup <slug> --worktree --keep-branch --yes` 删除临时工作树，同时保留 `autoresearch/<slug>` 在本地可用，或 `--worktree --branch --yes` 删除两者。脏工作树和未合并的分支删除需要 `--force`。
**工作树中使用的状态文件：**
| 文件 | 用途 |
| ------------------------ | ------------------------------------------------------------------- |
| `autoresearch.md` | 运行规范：目标、指标、方向、作用域文件、约束 |
| `autoresearch.sh` | 基准测试脚本。必须打印 `METRIC name=<n> value=<v> unit=<u>` |
| `autoresearch.checks.sh` | 可选设置工件。退出 0 = 可接受候选人 |
| `autoresearch.jsonl` | 创建/追加迭代期间。排除在运行程序提交之外 |
| `autoresearch.meta.json` | 运行者拥有的元数据，包括基准。排除在提交之外 |
**判决类别：** `keep`（改进 + 检查通过）、`discard`（未改进）、`incorrect`（检查失败或提交钩子拒绝）、`crash`（基准测试出错）、`timeout`（代理超时）。
**标志：** `--provider <claude|opencode|codex>` 强制使用提供者。 `--max-iterations <N>` 在 N 次迭代后停止。 `--stop-after <N>` 在连续 N 次丢弃后停止。 Ctrl+C 在迭代之间暂停；`resume` 从您离开的地方继续。
参见 [docs/autoresearch-walkthrough.md](docs/autoresearch-walkthrough.md) 获取端到端示例。
者支持
Shaka 集成以下四种 AI 编程助手：
| 提供者 | | 钩子 | 命令 | 技能 + 代理 |
| ----------- | ------------------------------------- | -------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------- |
| Claude Code | MCP 服务器（`shaka mcp serve`） | `~/.claude/settings.json` 中的子进程钩子 | `claude/skills/<command>/SKILL.md` | `aude/skills/`，`~/.claude/agents/`| opencode | 生成插件中的原生工具 | `~/.config/opencode/plugins/` 中的进程内插件 | `~/.config/opencode/commands/` | `~/.config/opencode/skills/`，`~/.config/opencode/agents/` |
| Codex | MCP 服务器（`shaka mcp serve`） | `~/.codex/hooks.json` 中的包装脚本 | `~/.agents/skills/<command>/SKILL.md` | `~/.agents/skills/`，`~/.codex/agents/*.toml` |
| Pi | 通过 `pi.registerTool()` 的原生桥接 | `~/.pi/agent/extensions/shaka.ts` 中的生成扩展 | `~/.pi/agent/prompts/` | `~/.pi/agent/skills/`，前缀为 `shaka-` / `shaka-agent-` |
您只需编写一次钩子 — 提供者特定的适配器将处理转换。有关钩子抽象、事件映射和工具集成的详细信息，请参阅 [提供者](docs/providers.md)。
## 安全
安全验证器钩子（`security-validator.ts`）在匹配的 `tool.before` 事件上运行，检查：
- **Bash 命令** 是否与 `system/security/patterns.yaml` 中定义的模式匹配
- **文件路径** 是否匹配读取/写入操作（阻止访问敏感目录）
- **灾难性操作** 被直接阻止（例如，`rm -rf /`）
- **危险操作** 触发确认提示
安全事件记录到 `memory/security/`。
```yaml
# system/security/patterns.yaml
version: "1.bash:
blocked:
- pattern: "rm -rf /"
reason: "文件系统销毁"
confirm:
- pattern: "git push --force"
reason: "强制推送可能导致提交丢失"
alert:
"curl.*\\|.*sh"
reason: "将 curl 管道传输到 shell"
paths:
zeroAccess:
- "~/.ssh/id_*"
readOnly:
- "/etc/**"
confirmWrite:
- "**/.env"
noDelete:
- "**/.git/**"
```
**计划中：** 基于配置的允许/拒绝目录列表，每个代理的能力授予。
## 计划功能
这些是未来开发的想法，尚未实现：
- **交互式 TUI** — `` 作为独立的终端接口
- **会话管理** — 跨 CLI 调用（`shaka start`，`shaka resume`，`shaka sessions`）的持久会话
- **工作流早期退出** — 循环的 `until` 条件（在无更改、哨兵输出或验证命令通过时停止）
- **功能填充** opencode 的子代理事件和后台子代理
## 开发
需要 [Bun](https://bun.sh) 和 [just](https://github.com/casey/just)。
```bash
bun install # 安装依赖
just check # 运行所有检查（类型检查 + lint + 测试）
just test # 运行测试
just typecheck # 运行类型检查器
just lint linter
just format # 格式化代码
```
### 端到端测试（Docker）
```bash
just e2e # 运行所有端到端测试
just e2e-claude # 仅 Claude Code 端到端测试
just e2e-opencode # 仅 opencode 端到端测试
just e2e-codex # 仅 Codex 端到端测试
just e2e-pi # 仅 Pi 端到端测试（挂载 ~/.pi/agent/auth.json 以测试身份验证路径）
```
## 先前的工作
从以下项目中学习：
- **[PAI](https://github.com/danielmiessler/Personal_AI_Infrastructure)** — 钩子系统、技能模式、内存架构
- **[PAI-OpenCode](https://github.com/Steffen025/pai-opencode)** — PAI 到 opencode 的移植、钩子到插件的转换
- **[Ren](https://github.com/erskingardner/ren)** — 决定性优先哲学、干净的目录结构
- **[openclaw](https://github.com/openclaw/openclaw)** — 网关模式、类型化工作流、多通道方法
- **[opencode](https://github.com/anomalyco/opencode)** — 提供者抽象、插件架构
- **[Claude Code](https://github.com/anthropics/claude-code)** — 钩子系统、上下文注入、子进程模型
- **[Codex](https://github.com/openai/codex)** — 子进程钩子、代理 TOML 格式、MCP 集成
## 许可证
MIT
连接信息
猜你喜欢
暂无推荐服务器