Agency Agents 教程：只安装需要的角色，并先看写入位置
Agency Agents 是一个 persona 目录。官方 README 当前称有 230 多个角色，按工程、设计、产品、营销、财务等 division 分类。每个角色是 Markdown 指令，真正调用模型和工具的是 Codex、Claude Code、Cursor 等宿主。
1. 目录、转换和执行是三层
division 目录中的 persona 是源文件，通常写明身份、工作流、交付物、成功指标和沟通方式。convert.sh 把这些源转换成不同宿主需要的 agent、rule 或 conventions 文件；install.sh 再把结果写到项目级或用户级目录。
安装后，宿主决定 persona 能读哪些文件、调用哪些工具和使用什么模型。角色文件里的“production-ready”属于项目方定位，不能替代权限审查、测试和人工验收。
2. 先 dry-run，再按范围安装
克隆官方仓库后先查看可选团队：
./scripts/install.sh --list teams
针对 Codex 只装工程 division，先看 dry-run：
./scripts/install.sh --tool codex --division engineering --dry-run
确认输出的目标目录与文件名后，再去掉 --dry-run。如果只需要前端或安全角色，使用 --agent 精确选择。这样比一次塞入全部 persona 更容易检查冲突和更新。
3. 不同宿主并非完全等价
Cursor 把角色转换成项目里的 .cursor/rules；OpenCode 可以写项目目录，也可以复制到用户配置；Aider 不会把约百万 token 的全部正文放进上下文，而是生成 CONVENTIONS.md 索引，需要时再读取具体 persona。
这些差异会改变触发方式和上下文占用。迁移宿主时要读对应 integration README，不能假设同一 persona 在所有工具里都自动触发或拥有相同权限。
4. 桌面 App 能做什么
Agency Agents App提供可搜索目录、目标工具选择和本地安装 ledger。ledger 记录源 hash、渲染 hash、目标、范围和项目路径，因此能识别 current、outdated、modified、removed 或 foreign，并在覆盖或删除修改过的文件前备份。
App 本身不运行 agent，也不是 catalog 的替代品。它无账号、无遥测，GitHub OAuth 仅在使用 GitHub 功能时可选。macOS 包已签名和公证；v0.3.1 的 Windows 安装器仍未签名，首次运行会出现 SmartScreen。
5. 更新与回滚
主 catalog 没有 release 号，应记录安装时的 commit。脚本安装前先用 Git 查看差异；桌面 App 可以根据 source/rendered hash 识别漂移。发现本地 persona 已手改时，不要直接覆盖，先保存差异或复制成自己的角色。
桌面 App v0.3.1 修复 Linux AppImage 污染子进程 LD_LIBRARY_PATH、Windows 离线缺 WebView2 时白屏，以及 Homebrew 7 需要 trust 的安装问题。这个版本号描述安装器，不代表 catalog 内容被冻结。
6. 商业化判断
主目录和 App 都以 MIT 发布，App 明确无账号和云同步。README 有 GitHub Sponsors 入口，但没有充值、额度分发、订阅销售或付费解锁角色，因此不按严重商业漏斗隔离。
7. 与 wshobson/agents 对比
wshobson/agents是可分装的 plugin marketplace，包含 agent、skill、command 和 orchestrator，安装一个插件时只加载该插件组件。Agency Agents 主要提供 persona 目录和跨宿主转换、安装。
需要命令、技能和多 agent 编排时，wshobson/agents 的结构更完整。只想选一个角色模板、阅读后部署到指定宿主，Agency Agents 更轻。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
适合谁用
适合为不同任务准备有明确交付格式的 persona，或学习角色提示词如何写工作流和成功指标。不要一次安装全部角色再期待宿主自动组成团队；应先选一个具体角色，在小任务中检查它读了哪些文件、调用什么工具、输出是否符合仓库规则。
采用建议
Agency Agents 适合把 persona 当作可审阅、可选装的配置资产。先用 dry-run 和单角色安装验证路径，阅读角色正文并按宿主权限测试；大批量安装会提高更新和冲突成本。
原教程未展开的系统信息
核心功能
230+ 角色目录
角色按 division 存放，每份文件包含身份、任务流程、交付物、成功指标和沟通方式，可直接使用或作为自定义模板。
架构与数据流
主仓库是 persona 的权威目录，division 下的 Markdown 文件是源。convert.sh 为各宿主生成原生格式，install.sh 负责选择 tool、division、agent 和安装范围。独立 Tauri/Svelte 桌面应用读取同一目录，做确定性渲染并用本地 ledger 跟踪安装状态；实际模型调用、工具权限和执行仍由 Claude Code、Codex、Cursor 等宿主负责。
技术栈和运行条件
语言
Markdown persona、Shell 转换/安装脚本；桌面应用为 Tauri 2（Rust）+ Svelte 5
框架
跨 Claude Code、Codex、Cursor、Gemini CLI、OpenCode 等宿主的角色目录
关键依赖
- Git 与 shell，用于脚本安装路径
- 至少一个受支持的 agent 宿主
- 桌面 app 构建需要 Rust、Node 22+ 与 Tauri 2 平台依赖
运行环境
脚本写入宿主的项目级或用户级配置；桌面 app ledger 保存在本机，无账号和遥测
常见问题
Agency Agents 主仓库的版本和桌面 app 版本一样吗？
不一样。主 catalog 没有正式 release；v0.3.1 属于独立桌面 app。
必须安装全部 230 多个角色吗？
不必。安装脚本支持 --division 和 --agent，先 dry-run 再安装更容易维护。
Agency Agents App 会自己运行这些 agent 吗？
不会。App 只负责浏览、转换、安装和跟踪 persona，执行仍由宿主负责。
Windows 版 Agency Agents App 已签名吗？
截至 v0.3.1 尚未签名，首次运行会出现 SmartScreen；macOS 构建已签名和公证。