AgentWeave

AgentWeave 是一个面向 Apple Silicon 的 macOS 14+ 原生工具，用来把同一套 Skill 和 Markdown 指令同步到其他编码 Agent。

• Skill：把源目录下的一级 Skill 子目录以软链接形式同步到多个目标目录。
• Markdown：选择一个或多个已有目标 Markdown 文件；没有目标文件时可配置新文件路径，并以原子写入方式完整覆盖。
• 记录：持久化最近 200 次操作及其结果，支持清空。
• 技术栈：Swift 6、SwiftUI、AppKit 文件选择器、FileManager、Codable JSON；目标架构为 arm64，不生成 Intel slice。

快速启动

需要安装完整 Xcode（建议 Xcode 16 或更新版本），仅安装 Command Line Tools 不足以构建 macOS .app：

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

使用 Xcode 打开工程：

open AgentWeave.xcodeproj

选择 AgentWeave scheme 和 My Mac 运行目标，然后按 ⌘R 启动；按 ⌘U 运行单元测试。

命令行编译与测试

在仓库根目录执行：

xcodebuild \
  -project AgentWeave.xcodeproj \
  -scheme AgentWeave \
  -destination 'platform=macOS,arch=arm64' \
  -derivedDataPath .build/debug \
  build

xcodebuild \
  -project AgentWeave.xcodeproj \
  -scheme AgentWeave \
  -destination 'platform=macOS,arch=arm64' \
  -derivedDataPath .build/test \
  test

仓库同时提供 Package.swift，安装匹配的 Swift/SDK 工具链后可执行 swift test。

生成 Release 包

仓库提供可重复执行的 arm64 打包脚本：

./Scripts/build-release.sh

脚本会检查当前是否选择了完整 Xcode，然后执行干净的 Release 构建、完整的 ad-hoc 本地签名和签名校验。ad-hoc 签名会封装应用资源，避免未封装资源的临时签名被 macOS 判定为应用损坏。产物位于：

dist/AgentWeave-0.1.3-macOS-arm64.zip
dist/AgentWeave-0.1.3-macOS-arm64.zip.sha256

ZIP 中包含完整的 AgentWeave.app。版本号从 Xcode 工程的 MARKETING_VERSION 自动读取，修改版本号后文件名会同步变化。

校验下载包：

cd dist
shasum -a 256 -c AgentWeave-0.1.3-macOS-arm64.zip.sha256

GitHub Actions

仓库包含两个自动化工作流：

• CI：对 main 分支的 push 和 pull request 执行 arm64 macOS 构建及单元测试。
• Release：推送 v* 标签时校验标签版本与 MARKETING_VERSION 一致，运行测试、执行打包脚本，并自动创建 GitHub Release、上传 ZIP 和 SHA-256 文件。

发布 0.1.3 的示例：

git tag v0.1.3
git push origin v0.1.3

当前 ad-hoc Release 流程不需要仓库密钥。未来启用 Developer ID 签名和 Apple 公证时，应把证书和公证凭据保存在 GitHub Actions Secrets 中，不要提交证书、私钥或密码文件。

安装和启动 Release

1. 双击 ZIP 解压。
2. 把 AgentWeave.app 拖入“应用程序”目录。
3. 从 Finder 的“应用程序”中双击启动，或执行：

open /Applications/AgentWeave.app

也可以不安装，直接启动刚构建的应用：

open .build/release/Build/Products/Release/AgentWeave.app

当前 Release 包使用 ad-hoc 本地签名，未使用 Developer ID 证书，也未提交 Apple 公证，仅适合本机开发验证或可信环境内测试。若 macOS 阻止首次启动，请先确认使用的是最新生成的 ZIP，然后在 Finder 中右键点击 AgentWeave.app，选择“打开”，再确认一次；不要全局关闭 Gatekeeper。面向其他用户正式分发前，应配置 Developer ID Application 证书、Hardened Runtime 和 notarization。

如果曾安装过旧的未正确签名版本，请先把旧 AgentWeave.app 移到废纸篓，再解压并安装新包，避免 Finder 继续启动旧副本。

默认路径

默认路径通过 FileManager.default.homeDirectoryForCurrentUser 动态生成，不包含硬编码用户名：

• Skill 源目录：~/.agents/skills
• Markdown 源文件：~/.agents/AGENTS.md

目标目录和文件由用户通过 macOS 原生选择器明确添加。配置与历史记录保存在：

~/Library/Application Support/AgentWeave/configuration.json
~/Library/Application Support/AgentWeave/history.json

写入采用原子方式，且不会保存 Skill 或 Markdown 正文副本。

工程结构

AgentWeave/
├── Models/          配置、目标、同步结果和历史模型
├── Persistence/     原子 JSON 配置与历史持久化
├── Resources/       AppIcon 与 Asset Catalog
├── Services/        路径验证、Skill/Markdown 同步、并发门闩
├── ViewModels/      异步任务编排、状态淡出与持久化协调
└── Views/           Skills、Markdown、同步记录、设置及通用组件
AgentWeaveTests/     使用临时目录的核心服务与持久化测试
Design/AppIconSource.png  最终应用图标源文件

同步服务与 SwiftUI 页面分离，所有耗时文件操作在后台任务中运行。同一目标的重复操作由界面状态和 SyncOperationGate 双重拦截。

Skill 安全规则

• 只为源目录中的一级 Skill 子目录创建软链接，不复制文件。
• 正确链接会跳过；错误链接只替换该链接。
• 替换错误链接时先创建临时链接，再备份并切换；失败会尝试恢复原链接。
• 同名真实文件或目录一律标记为冲突，不删除、不覆盖。
• 不删除目标目录独有内容，不修改源目录。

Markdown 安全规则

• 完整读取源文件，以原子写入覆盖目标文件，不合并、不双向同步。
• 目标不存在时，仅在现有且可写的父目录中创建文件。
• 不自动创建缺失的多层父目录。
• 源目标解析为同一文件、源不可读或目标不可写时拒绝操作。

App Sandbox 与直接分发

MVP 的 Xcode target 设置为 ENABLE_APP_SANDBOX = NO。原因是应用需要直接访问用户主目录内多个隐藏目录，而直接分发场景下关闭沙盒可以避免为每个长期配置维护 security-scoped bookmark。

影响：应用进程不受 App Sandbox 的文件系统隔离保护。因此 AgentWeave 只对用户明确配置的 Skill/Markdown 源路径和目标路径执行同步；冲突时绝不删除真实文件或目录。正式发布仍建议启用 Hardened Runtime、使用 Developer ID 签名并完成 notarization。如果未来改为 Mac App Store 分发，需要启用 Sandbox，并为选择的路径持久化 security-scoped bookmarks。

测试覆盖

测试全部使用唯一的系统临时目录，覆盖：新建/跳过/修复 Skill 链接、真实文件与目录冲突、源目录缺失、目标不可写、Markdown 覆盖与创建、源目标相同、缺失父目录、配置和历史重新加载、200 条历史上限、重复任务拦截。