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/<skill-name>/
審查變更後：
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 <name> <path>
此指令會建立權威專案骨架並同步其 .agents/ 運行時。將現有的未管理運行時資源或與其他路徑繫結的專案名稱視為衝突，需由使用者處理；請勿繞過它們。
專案配置歸屬於：
~/aikito/projects/<name>/agent.toml
~/aikito/projects/<name>/AGENTS.md
~/aikito/projects/<name>/memory/
使用以下指令同步並驗證：
aikito show projects
aikito show project <name>
aikito sync project <name> --dry-run
aikito sync project <name>
aikito status
aikito diff
aikito show memory
專案指令和記憶體保持與權威來源的連結。專案技能遵循 sync_mode：link 保留符號連結；copy 產生受管理的副本以用於專案 Git 追蹤。使用 aikito status 檢測副本技能的漂移，並使用 aikito diff 將其與權威技能進行比較。同步會拒絕取代已漂移的副本；合併應保留的變更，或僅在審查後使用 aikito sync project <name> --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/<name>/memory/。
aikito show memory [target]
aikito edit memory <target>
使用獨立的 durable-memory 技能來決定何時知識足夠持久以進行持久化、哪個範圍擁有它，以及如何對其進行版本控制。
採用
在匯入現有代理配置之前預覽：
aikito adopt
僅在使用者審查計畫並解決指令衝突之後：
aikito adopt --apply
應用程式會在 ~/.aikito/backups/adopt_<timestamp> 下建立帶有時間戳記的備份。採用會將資源匯入工作空間；代理原生配置僅在明確同步期間才會變更。
驗證與當前行為
每次寫入後，執行最狹窄的相關狀態指令並檢查報告的目標。使用 aikito <command> --help 作為已安裝版本所支援選項的權威參考。當從原始碼檢出工作時，請查閱其根目錄的 README 和相關連結文件，以了解當前架構和安全模型。