Aikito 是做什么的？
用途
将 Aikito 作为持久化代理资源的规范、Git 管理来源，并将这些资源同步到受支持的编码代理和项目中。
心智模型
保持 CLI 源码和用户工作空间分离：
~/aikito-src CLI 源码检出
~/aikito 规范用户工作空间
工作空间包含事实来源：
~/aikito/
├── agents.toml
├── skills.toml
├── subagents.toml
├── mcps/
├── global/AGENTS.md
├── skills/
├── memory/
└── projects/<name>/
代理配置目录和项目 .agents/ 目录是运行时入口点，而非独立来源。首先修改规范工作空间文件，然后通过 CLI 同步它们。
当工作空间不是 ~/aikito 时，使用 AIKITO_DIR。使用已安装的 aikito 命令，而非假定 CLI 位于工作空间内。
引导
当 CLI 未安装时，使用官方源码仓库并将其检出与未来的工作空间分开：
git clone https://github.com/lsaint/aikito.git "$HOME/aikito-src"
export PATH="$HOME/aikito-src/bin:$PATH"
克隆之前，验证目标目录不包含无关的用户数据。未获用户指示，不要覆盖现有检出。
初始化并检查工作空间：
aikito init workspace ~/aikito
aikito status
aikito init workspace 拒绝 CLI 源码树、另一个源码检出以及无法识别的非空目录。不要试图绕过这些保护。初始化后，在同步任何内容之前检查生成的文件。
安全协议
- 从只读发现开始：检查相关的规范文件，运行
aikito status，并使用资源特定的状态命令。 - 先执行
aikito adopt而不带--apply。向用户展示采纳计划、冲突和凭据处理方式，然后再应用。 - 对支持的同步命令使用
--dry-run。 - 将未管理的目标和冲突指令视为需要用户决策的事项。不要静默覆盖它们。
- 将 API 密钥、令牌、密码和 OAuth 材料排除在 Aikito 工作空间和 Git 之外。在规范 MCP 配置中存储环境变量引用。
- 在任何显式的强制或修剪操作之前发出警告，并将其范围限定在已审查的目标。
- 不要将本地 Git 仓库视为安全的发布对象。在添加远程或推送之前，检查记忆和配置中的私有数据。
- 保留工作空间和目标代理配置中的无关用户更改。
资源路由
全局指令和技能
规范来源：
~/aikito/global/AGENTS.md
~/aikito/skills.toml
~/aikito/skills/<技能名称>/
审查更改后：
aikito sync global --dry-run
aikito sync global
aikito status
aikito show skills
aikito show skill <target>
aikito edit skill <target>
不要将生成的代理原生指令或技能条目作为独立来源编辑。
在添加、重命名或删除全局技能时，将此更改视为跨运行时迁移，而非仅目录编辑：
- 更新
skills.toml、公共导出允许列表以及对旧技能名称的引用。 - 验证每个加载全局技能的受支持代理在
agents.toml和aikito init模板中具有正确的skills_path。不要假定代理 CLI 及其 IDE 使用相同的全局技能目录。 - 运行相关测试，然后运行
aikito sync global和aikito status。 - 检查每个受管理的代理目标，确认新技能可见且旧名称的失效链接已消失。
- 除非项目有意覆盖或复制它，否则将全局技能保留在项目
agent.toml文件之外。
项目
工作空间是事实的中央来源，通常仅存在一份。项目注册代表一个代码目录及其特定于项目的代理资源。当请求的指令、技能选择或记忆是项目特定的，而当前代码目录未注册时，询问用户是否希望注册它。不要为全局资源注册项目。
确认后，从其代码目录初始化项目：
aikito init project
目录名称和当前路径是默认值。需要时使用显式参数：
aikito init project <名称> <路径>
此命令创建规范项目骨架并同步其 .agents/ 运行时。将现有的未管理运行时资源或绑定到另一路径的项目名称视为用户的冲突；不要绕过它们。
项目配置属于：
~/aikito/projects/<名称>/agent.toml
~/aikito/projects/<名称>/AGENTS.md
~/aikito/projects/<名称>/memory/
使用以下命令同步和验证：
aikito show projects
aikito show project <名称>
aikito sync project <名称> --dry-run
aikito sync project <名称>
aikito status
aikito diff
aikito show memory
项目指令和记忆保持与规范来源的链接。项目技能遵循 sync_mode：link 保留符号链接；copy 生成用于项目 Git 跟踪的受管理副本。使用 aikito status 检测复制技能的漂移，使用 aikito diff 将其与规范技能进行比较。同步拒绝替换漂移的副本；合并应该保留的更改，或仅在审查后使用 aikito sync project <名称> --force。
目标 .agents/skills/ 和 .agents/memory/ 目录由 Aikito 独家管理。未知条目视为冲突，项目同步绝不会删除它们。不要在那里存储无关文件。
MCP 服务器
规范来源：
~/aikito/mcps/*.toml
预览、应用和验证：
aikito sync mcp --dry-run
aikito sync mcp
aikito show mcp
仅在实时代理检查有用时使用 aikito show mcp --live。对受支持的认证流程使用 aikito auth mcp <agent> <server>。切勿打印、持久化或提交捕获的凭据。
子代理
规范来源：
~/aikito/subagents.toml
~/aikito/subagents/
预览、应用和验证：
aikito sync subagents --dry-run
aikito sync subagents
aikito show subagents
aikito show subagent <target>
aikito edit subagent <target>
在使用 --prune 之前审查孤立的受管理文件。切勿仅仅为了让状态变为绿色而强制管理未管理的目标。
记忆
全局记忆属于 ~/aikito/memory/。项目特定的记忆属于 ~/aikito/projects/<名称>/memory/。
aikito show memory [target]
aikito edit memory <target>
使用单独的 durable-memory 技能来决定哪些知识足够持久以保留、哪个作用域拥有它以及如何进行版本控制。
采纳
在导入现有代理配置之前预览：
aikito adopt
仅在用户审查计划并解决指令冲突后：
aikito adopt --apply
应用会在 ~/.aikito/backups/adopt_<timestamp> 下创建带时间戳的备份。采纳将资源导入工作空间；仅在显式同步期间更改代理原生配置。
验证和当前行为
每次写入后，运行最窄的相关状态命令并检查报告的目标。使用 aikito <command> --help 作为已安装版本所支持选项的权威来源。从源码检出工作时，查阅其根目录下的 README 和相关链接文档以了解当前架构和安全模型。