开始使用

安装 fx，连接团队 manifest，并管理仓库、工具与编码 Agent。

各版本的变更见更新日志。请查看已安装版本的 fx <command> --help 和随包 Skill，确认当前可执行文件支持的功能。

按任务选择阅读入口：

• 新建工作区：安装，然后快速上手。
• 还没有 manifest：设置配套 CLI。
• 保持最新：更新工具和 Skill。
• 仓库较多：下载前选择仓库。
• 设置中断：判读结果并恢复。
• 编码 Agent：结构化结果与 bundled Skill。

环境要求

• Node.js ≥22；开发版本以 package.json 为准。Bun 也可以作为运行时。
• Git 位于 PATH 中。全局安装和 fx self update 仍需要 npm，包括使用 Bun 时。
• 工作区需要团队提供的 manifest，或自行创建的 manifest。只设置配套 CLI 时不需要。

支持 macOS 和 Linux。原生 Windows 适配器已实现，但 Windows 实机执行和 Agent 宿主激活尚未完成验证；目标为本地 NTFS 上的 PowerShell 5.1/7 和 cmd。参见 Windows 支持边界。

Bitbucket Git 认证

当 bitbucket-cli git --help 可用时，fx 会使用配套 CLI 已有的登录，通过 HTTPS 完成 manifest 初始化、仓库克隆与同步。只要服务器允许 HTTPS Git，Data Center PAT 具有仓库读取权限即可；即使 manifest 使用 SSH URL，也不需要 SSH key。地址转换仅对本次调用生效，已保存的 remote 保持不变。fx 不读取或保存 token；推送仍需要写权限。

首次克隆 manifest 前，先配置配套 CLI 的服务并登录。多个账号可通过 BITBUCKET_CONTEXT 选择初始化时使用的 context；工作区操作优先使用 manifest 声明的 context。用 bitbucket-cli git -- ls-remote <clone-url> 验证实际 Git 读取。配套 CLI 缺失或版本较旧时，继续使用普通 Git 认证，需升级配套 CLI 才能使用此能力。凭据被拒绝时会保留错误。单独执行 git fetch 仍需自行配置认证，或改用 bitbucket-cli git -- -C <dir> fetch upstream。此机制不支持递归子模块。

安装

公开包

对外分发使用 npmjs 上的 @angelmsger/fx，无需团队私有 Registry。

npm install -g @angelmsger/fx --registry=https://registry.npmjs.org/ --@angelmsger:registry=https://registry.npmjs.org/
fx --version

也可以从源码运行：

npm ci
npm run build
node bin/fx.js --help
node bin/fx.js --version

运行后续示例时，将 fx 替换为 node /absolute/path/to/fx-devkit/bin/fx.js。启动器读取 dist/，因此必须先构建。

PowerShell 执行策略阻止 .ps1 shim 时，可使用 npm.cmd 和 fx.cmd，无需更改策略。

更新

源码安装可通过 Git 更新 checkout，然后执行 npm ci 和 npm run build。使用 fx self info --format json 查看当前版本及包更新来源。参见更新说明。

快速上手

你只需要团队提供的 manifest 来源，以及工作区要放的目录。可以直接告诉 Agent：“请用 fx 根据这个 manifest，把工作区准备到这个目录。”自己操作终端时，先预览再执行：

fx init ./work --from <manifest-repository> --dry-run
fx init ./work --from <manifest-repository>

fx 会检查来源，完成已授权的本地工具与配置准备，克隆所选仓库，并准备 Agent 指南和 Skill。工作区名称自动生成并避开已有注册，已有文件和已完成的工作会保留。批准新命令前，请检查展示的准确参数。

看到 Ready to work 即可开始工作。若需要个人登录、权限或批准，fx 会集中列出剩余事项。处理后使用返回的继续命令：

fx init --resume --workspace work

终端输出会直接列出个人登录命令和继续命令。在自己的终端完成登录，解决所列前置条件后运行继续命令即可。

续跑会验证当前状态并跳过已完成的准备，不会重新导入目录来源或重建已有仓库。无需自行选择内部阶段或再组合一套诊断命令。

新工作区默认选择全部共享仓库。需要减少首次下载时，先选择仓库，给初始预览和执行都加 --repos。已有目录自动纳入管理。日常更新使用 fx sync，查看仓库状态使用 fx status。

不用 manifest 设置配套 CLI

没有团队 manifest 时，不带目录运行 fx init，即可在本机设置 fx 支持的配套 CLI。它会列出这些工具并询问需要哪些，按 Enter 选择全部。直接写出名称则不再询问：

fx init
fx init --tools bitbucket-cli,jira-cli --dry-run
fx init --tools all

fx 会安装尚未安装的工具，让每个工具把自己的 Skill 与 fx 自身的 Skill 一起安装到你的编码 Agent 中，并检查你是否已登录。对于尚未设置的工具，fx 会询问是否启动该工具自己的设置，例如 bitbucket-cli config init，它会询问服务地址和你的凭证。如果你拒绝、传入 --yes 或在没有终端时运行，fx 会改为列出这些命令；运行之后再执行一次 fx init --tools <names> 即可确认。已有的工具保持原样；更新是单独的一步。

这样不会注册工作区，也不预设任何内容。有 manifest 时，fx init <dir> --from <manifest> 会决定工具，并为你填好每个服务的地址。

保持工具和 Skill 最新

fx self update --yes   # 更新 fx，再更新你已安装的 fx Skill 副本
fx tool update --all   # 更新你已安装的每个配套 CLI，再更新它的 Skill

fx tool update --all 只更新已经安装的配套 CLI，不会安装新的工具；那是 fx tool install 的事。fx 每安装或更新一个工具，都会让它再为你的编码 Agent 安装一次自己的 Skill，这样 Agent 读到的就是你现在这个版本的说明。fx self update 最后会让新的 fx 刷新比它旧的自身 Skill 副本，fx skill update 也可以单独做这件事。在工作区内，同样的命令会更新工作区使用的工具，fx sync 也会刷新 Skill。

发现和管理工作区

fx workspace list 可在任意目录运行，即使没有默认工作区，或某项注册的根目录、manifest 已缺失。fx workspace show <name> 返回身份、来源、健康状态与选择上下文，不要求 manifest 完整。用 fx status --workspace <name> 显式选择；未指定时，当前目录所属工作区优先于 default_workspace。

fx workspace list
fx workspace show work
fx status --workspace work
fx config set default_workspace work

目录已移动时，用 workspace relocate <name> <new-dir> 更新注册；它不会移动或重新克隆 checkout。用 workspace rebind <name> --from <source> 更换 manifest 来源，同时保留工作区身份和个人选择。将同一物理目录注册为第二个名称不等于迁移。

workspace unregister <name> 解除托管并保留业务 checkout。先用 --dry-run 预览生命周期操作，检查受管资源清理和冲突；外来文件会保留。

下载前选择仓库

初始化时用 --repos 限制首次下载，名称必须存在于已检查的 manifest；--no-repos 表示空仓库集合。重复 init 时不带这两个参数会保留已有选择。

fx init ./work --from <manifest-repository> --repos example-api --dry-run
fx init ./work --from <manifest-repository> --repos example-api

已有工作区中，select 替换集合，pick 加入名称，unpick 移除名称。选择操作不删除文件，也不会自行下载 checkout；随后运行 sync 获取或更新已选仓库。

fx repo select example-api
fx repo pick example-web
fx sync --dry-run
fx sync
fx repo select --all
fx env select dev
fx env select --none
fx env select --all

仅使用显式 Git URL、未绑定代码托管 provider 的 manifest，同步仓库无需配置代码托管用户名。

未下载的仓库仍保留在完整目录中。可以直接让 Agent 处理该仓库的任务，或运行 fx repo show <name>：返回的 next_steps 会在正确的工作区补选仓库并同步下载，随后在返回的路径继续工作。

--all 持续跟随团队完整集合，包括未来新增项；逐个选中目前全部名称仍然是固定列表。--none 选择空集合。清单与选择结果展示当前模式，避免将空选误认为未设置默认值。

只有这些命令会改变环境选择。fx login 不会询问它：未设置时覆盖所有已声明的环境并说明如何收窄，--env 只限定这一次执行，不改变选择。

仓库选择只控制共享条目；本机单独注册的仓库和 manifest checkout 仍单独管理。select 接收以空格分隔的名称，init 的 --repos 接收以逗号分隔的列表。

判读仓库状态

fx status 标明工作区并展示未跟踪文件数。fx status --dirty 同时查找已跟踪文件的修改与新建的未跟踪文件。JSON 保留 dirty 表示已跟踪文件或索引修改，新增 uncommitted 表示任一类未提交工作。被忽略文件不计入未跟踪工作。空结果解释是未选择仓库，还是没有仓库匹配筛选。

工作区根目录不是 Git 仓库，因此 fx status 还会返回 stray_entries：根目录下既不是 checkout、派生指南、fx 维护的 Go 工作区、Agent 或服务配置，也不是工作台的文件和目录。fx doctor 在 root 组里逐项列出，级别为警告，不影响就绪判定。

sync 保留工作文件和分支。应查看计划动作：已跟踪文件修改可能触发 skip_dirty；checkout 位于其他分支时，只更新被跟踪的分支引用。空的 upstream 会被跳过，因为没有可 fast-forward 的内容；缺少被跟踪分支的 upstream 同样会被跳过，但会作为需要检查的问题报告。如果更新会覆盖分支未跟踪的本地文件（包括 .env 这类被忽略的文件），sync 会保持该 checkout 不变，报告 outcome local_files_in_the_way，并在 files_in_the_way 中列出这些文件；将它们移开后再次运行 sync。status 默认不 fetch，需要刷新远端比较时显式加 --fetch。

在终端里，sync 和 init 只显示需要关注的仓库或 Skill 行，成功的由状态行计数。两者最后都按阶段各给一行结论，再按解决方式分组列出阻塞项：登录、服务拒绝的访问，或本机连不上的服务器，后者会给出重新检查的命令。--verbose 会显示每一行，管道或 --format json 仍会收到全部行。

核心概念

工作区和 manifest

工作区是注册过的普通目录，内含独立 checkout 和受管理的 Agent 资源。manifest 源位于 ~/.fx/workspaces/<name>/source，fx 不会在受管理的工作区根目录运行 Git。同步不会通过切分支、reset 或 stash 覆盖脏工作区、分叉状态或其他分支上的工作。

不属于任何仓库的产物放在工作区根目录的 .workbench/ 下：每个任务一个带日期的目录，存放报告、计划和证据；worktrees/ 放 git worktree add 的目标；tmp/ 放随时可以丢弃的内容。派生指南向 Agent 说明同样的规则。fx 不会写入该目录。

根目录的 AGENTS.md 是 fx 派生的唯一一份指南，各 Agent 会自行读取。Claude Code 从 2.1.277 起也是如此，前提是工作区根目录及其上级目录中没有 CLAUDE.md 或 CLAUDE.local.md。一旦存在，Claude Code 会改读该文件而不读指南，因此请在其开头写上 @AGENTS.md。

workspace、environments、tools 和 members 文档保存共享事实；可选 harness 文档描述 MCP 和规则。用以下命令查看字段：

fx manifest explain 'repos[].upstream'
fx manifest schema --kind tools

个人配置

全局配置记录工作区和偏好。Agent 选择在同一 FX_HOME 注册的工作区间共享；仓库与环境选择属于各自工作区。repo add 登记本机引用，repo remove 仅移除引用，保留文件。配置导出不复制凭据、信任记录或 manifest checkout。

能力、提供者与配套工具

capability 表示代码托管、CI、日志、错误追踪等意图，provider 通过配套 CLI 实现它。manifest 绑定能力、提供者和环境坐标。can 查询就绪，where 查询坐标，release check 查询声明的发布检查项。

工作区级能力一次绑定：code-host、issue-tracker、knowledge-base、im、channel、calendar、meeting、task、worklog；环境级能力按平台实例绑定：error-tracker、log-store、metrics、ci、cluster。不带目标的 fx can 列出这些能力以及当前工作区里各由谁提供；fx manifest providers 列出已绑定的内容和每个能力可选的 provider。calendar 是日程与忙闲所在；meeting 是承载在线会议及其录制、纪要的会议系统，在一个产品里排日程、在另一个产品里开会的团队两者都绑定。在企业微信上，wecom-calendar 通过 WeCom CLI 列出其机器人可见的日程，wecom-calendar-cli 则在每位成员自己日历的本地镜像中连同历史一起搜索；登录以及用 wecom-calendar-cli sync 填充镜像都由成员自己完成。

将工作区能力 channel 绑定到 wecom-channel-cli 即可安装 CLI 和 Skill。就绪检查通过代理套接字运行 doctor。频道监听会排除以同一 Bot 身份发送的消息，包括其他客户端使用该身份发送的内容。升级 CLI 时应同时升级 broker，并按配套 CLI 的迁移指南核对旧监听检查点或 relay 队列。

智能机器人对话可在受限 worker 工作区中将 im 绑定到 wecom-chat-cli。fx can im 检查当前任务的访问权限并返回读取命令，不输出对话内容。使用 fx tool install wecom-chat-cli 安装 CLI；包内 Skill 需通过隔离宿主手动安装。参见worker 配置。

metrics 由 prometheus-cli 提供。它的坐标是服务的抓取 job：where 输出一条 up{job="..."} 查询，返回该服务各抓取目标的标签集合，可作为编写后续选择器的起点。选择器匹配不到任何序列时查询仍然成功，因此指标不提供存在性探测，where --probe 对它报告 unknown，不作猜测。

tool list/show 展示工具要求，tool install/update 使用声明的安装器，login 引导设置。认证由各工具负责，包括已保存的凭据可以发往哪个服务。fx 为内置工具定义的命令无需确认即可运行；团队 tools.yaml 新增或覆盖的命令向量需要信任一次，向量改变后需要重新确认。口头确认手动步骤不能替代验证成功。

工具定义由内置目录与所选工作区的 tools.yaml 合并；工作区的工具链则是其中它真正使用的部分：被绑定 provider 驱动的工具，加上 tools.yaml 声明的工具。fx tool list 说明每个工具因何在此，--catalog 会再列出 fx 知道但没有被选用的工具。工作区优先级为 --workspace、FX_WORKSPACE、当前目录所属的已注册工作区、default_workspace；无法确定工作区时没有绑定可推导，因此列出内置目录。包管理器决定安装位置，工具由多个工作区共享。

tool install 和 tool update 必须指定名称或 --all，两者互斥。安装的 --all 补齐已启用且 PATH 缺失的工具；更新的 --all 选择当前工具表中已启用且在 PATH 上的工具，在工作区内还会用 TOOLS_NOT_INSTALLED 通知列出被跳过的工具。显式名称可以选择被禁用的工具。无参数调用会在执行包操作前报错。包操作之后，每个被安装或更新的工具会为所选 Agent 安装自己的 Skill，行中的 skill 报告结果。

doctor 默认检查工作区声明的工具及所选环境中实际启用的 provider 依赖。未使用的内置工具仍可通过 tool list --catalog 或显式 doctor --tool <name> 查询；缺少它们不会导致无关工作区不健康。工具链本身覆盖 manifest 声明的全部环境（安装是整机的），而 doctor 的检查仍按所选环境收窄。活跃 provider 的依赖若被禁用，仍会报告检查不完整。

init/sync 使用相同的相关工具范围。缺少可选工具仍会显示，但不阻断准备。启用的 install_on_init 工具需要验证；已禁用的可选工具不会仅因这个安装标记而变成必需工具。

内置 Sentry 工具通过 npm 的 sentry 包安装；manifest 启用初始化安装时也适用。

共享服务设置与个人凭证

manifest 可声明 URL、context、组织和认证方式等公共 service 设置。init、显式 sync 和 login 通过配套工具自身的命令准备这些设置；后台 hook 只检查。声明的认证方式只是 fx 新建 context 时的默认值；你自己的 context 只要已经能访问声明的服务，无论用哪种方式登录都算就绪。使用 fx sync --only services --dry-run 预览。

配置和认证分开进行。每位成员通过配套 CLI 获取并保存自己的凭证。已有冲突设置保留并报告；sync 不执行个人登录。但它每次运行都会把你在同一服务上已有的登录关联到工作区的 context，在别处登录之后不需要再记着做什么。Sentry 仅写入工作区 .sentryclirc 的公共默认值，保留外来文件。

sync 的 stages.services 和 stage_details.services.items 表示阶段结果；init 在 sync 下嵌套这些字段。摘要保留阻塞与失败，--details 还包含成功条目。参见服务预设与恢复参考。

工具安装历史

fx tool history --format json
fx tool history bitbucket-cli --format json
fx tool inventory --format json

init、tool install 和 tool update 在 $FX_HOME/tool-history.json 记录尝试。installed 表示包管理器成功，但后续版本核验仍可能失败；单独的 started 不证明成功。dry-run 和 init 跳过的已有工具不产生记录。

tool inventory 的安装来源与 tool list/show 的定义来源分别表达不同事实：

依赖检查覆盖同一 FX_HOME 的全部已注册工作区，包括启用的可选工具和内置默认项。只有已确认由 fx 安装且没有剩余需求的工具才可成为 unused；其他 FX_HOME 和未注册项目不在检查范围。建议仅供人工判断，sync/doctor 从不卸载工具。读取失败或证据不足不能证明可以移除。

查询不会接管 PATH 中的工具，也不重建旧安装历史。完整字段见安装清单参考，数据范围见本机数据。

fx 伴生 Skill 与团队 Skill

fx 伴生 Skill 引导 Agent 使用 CLI。无需安装或注册工作区即可读取：

fx self info --format json
fx skill show
fx skill status

希望宿主自动发现副本时，使用 fx skill install --agent codex。--project 面向当前目录；--dir ./custom-skills 面向独立目录，不能与 --agent、--project 同用。独立 Skill 命令的目标选择不依赖工作区 Agent 配置。检测、替换与卸载规则见Skill 参考。

显式 install 将已识别副本刷新到调用 CLI 的版本，包括同版修复和替换较新副本。skill update 只刷新比调用 CLI 旧的已识别副本，覆盖所有 Agent 的目录，不新装副本；self update 会从新安装的 fx 运行它。init/sync 同版复用且不降级。外来内容替换需要确认和备份。卸载不改变 Agent 选择，后续 sync 可能再次安装。

skill status 报告安装版本与 activation: unverified。文件已安装不代表宿主已加载。按需读取随包指南。

团队 Skill 位于 manifest 的 skills/，由 init/sync 链接到所选宿主，并在根 AGENTS.md 生成目录。请从工作区根启动，子仓库中的发现行为没有保证。用 fx sync --only docs,skills 刷新；不要通过团队共享链接安装 fx 伴生 Skill，应使用用户副本或独立目录。

贡献共享知识

source push 可预览或提交所选源文件，保留源 checkout 的 HEAD、索引和工作文件。提交需要个人 fork 及其上游关系的证据，manifest 源须托管在 Bitbucket 或 GitHub 上。实际提交前阅读 fx source push --help 与贡献契约。

常用命令

用 fx <topic> --help 查看标准入口与兼容别名。集合参数同时接受重复参数和逗号分隔的值。

完整语法以 --help 和生成的 CLI 参考为准。

给编码 Agent

先执行 fx self info --format json。初始化任务读取返回的 initialization_guide，并持续使用同一准确入口。完整 Skill 提供其他任务的路由。

用 --format json 分开保存 stdout 结果与 stderr 进度、通知和错误。默认结果保留准备结论和全部阻塞项，--details 展开阶段证据。human 默认先显示任务结论和下一步。release check 的 human 输出在每个仓库开头先说明它将发布的内容：目标分支声明的版本、两个分支的最新提交，以及源分支上尚未合并到目标分支的提交数。开头分别统计失败、警告、未完成、通过和不适用的检查。已确认的问题按仓库列出；相同的不可用或部分结果按原因合并，并注明受影响的检查、仓库和恢复步骤。已确认的失败也可能同时未完成。只有检查已完成且无问题的仓库才进入完成分组；明确排除的检查与通过项分别统计。--details 展开各仓库的全部检查。没有确认失败但仍有未完成项时，通知为 RELEASE_INCOMPLETE；JSON 保留原有 ok/complete 语义及查询失败的结构化信息。缺少错误追踪项目时报告未完成，不再查询整个组织。在终端上还会加上颜色和符号、按宽度收窄表格，并以文本显示错误；管道或文件得到纯文本和 JSON 错误信封，NO_COLOR 去掉颜色。命令执行期间，终端上还会有一行状态行，显示已用时间、可计数工作的进度和正在等待的对象；命令结束后这一行消失，管道、文件、JSON 输出和 --quiet 都不会收到它。git 或安装器运行期间可能在同一终端上询问主机密钥或口令，这时状态行不再原地刷新，改为每五秒打印一行。显式 --fields 从完整报告提取字段，点路径保留为扁平键，例如 fx sync --format json --fields operation,preparation.state,items,summary。

发布版本优先读取源分支根目录的 VERSION 文件, 并在两个分支的最新提交上读取同一路径. 内容会去除首尾空白, 空内容保持为未知. 没有 VERSION 时, 继续从依赖文件 (如 package.json) 读取版本. 依赖检查仍读取依赖声明.

发布错误窗口可以使用相对时长, 或一对包含时区的明确时间. 绝对区间包含起点, 不包含终点; 要包含完整的一天, 终点使用当地次日零点. 例如:

fx release check fx-example-api --from 2026-04-01T00:00:00+08:00 --to 2026-04-15T00:00:00+08:00 --format json --details
fx repo version fx-example-api --ref main --baseline v1.2.0 --format json
fx repo version fx-example-sdk --path packages/client/package.json --format json

版本证据把引用固定到提交, 标明实际声明字段, 并沿第一父提交历史查找该字段最近一次值变更. 仅修改依赖不算版本变化. 历史基线比较从该引用以来的全部变更, 与尚未合入发布分支的提交分开. 源码版本或修改时间不能证明已发布. 历史缺失或查询预算耗尽时, 返回带有原因的部分证据. CLI 参考 说明如何在多仓发布检查中请求这些证据, 以及如何选择包路径.

自动发现版本证据时会跳过 requirements.txt 等只声明依赖的文件. 已存在但无法读取的受支持版本来源会使证据不完整, 不会隐式改选其他包; Gradle 可以使用相邻的 gradle.properties. Maven 支持字面版本, 或可从项目 properties 解析为字面值的单个 ${property}. 组合表达式、嵌套表达式或无法解析的表达式返回 VERSION_DECLARATION_UNREADABLE, 并保留证据不完整状态.

Sentry 证据保留匹配未解决查询且在窗口内活跃的已收集候选, 包括旧问题. 后续确认 resolved 或 ignored 的状态保留在审计证据中, 但不计入新问题判定, 并区分生命周期首次出现时间和列表/窗口时间. 分页或元数据失败会明确保留; 部分证据不能证明问题不存在. 状态与责任人反映读取各响应时的情况, 不代表历史窗口内的状态. 事件数的统计范围未知, 不能当作本轮新增事件次数. 错误检查按生命周期首次出现时间计数; 旧问题是否回归需要另行判断.

repo show 还返回 ownership_evidence: 仓库关联的业务范围、人员、团队和集体职责. 日期筛选只对当前成员文档中声明的有效区间求值, 不恢复历史快照, 也不决定委派谁.

准备就绪退出 0，未完成退出 12；预览只是计划。配置或执行异常保留原分类退出码，也可能返回部分 stdout。doctor.coverage 单独描述诊断覆盖；可选宿主激活未验证不会阻塞必需工作，文件存在也不证明激活。

发布报告成功生成后仍以 0 退出. ok 表示没有失败检查, complete 表示检查覆盖完整. evidence_complete 还包括已请求的仓库事实; 为 false 时应查看 facet_coverage 和失败原因. observed_at 是命令开始时间. 每个仓库记录自己的标准化时间区间; 仓库策略使用不同窗口时, 顶层区间为 null.

Init 会自行执行已授权的本地准备。结果保留已完成步骤；认证未完成时，不要重复这些步骤。

若需保存输出进行分析，请使用任务授权目录；只读姿态无法控制 shell 重定向。

先读 preparation.next：审阅预览、准备完成后继续原任务、执行 Agent 动作，或等待人工条件补齐。next_actions 只包含 Agent 可处理的动作；个人操作保留在阻塞项内并标为 actor: user。条件变化后才运行 resume。

一次阅读全部 preparation.blockers。next_actions 提供准确 argv、cwd、可选 env 坐标和审批要求；续跑时保留这些值，resume 继续已注册工作区。已有授权继续有效，新向量仍需审阅。不要凭注册或克隆推断成功，不要为获取明细重复写入，也不要将个人凭据放入 manifest。

文件冲突的逐项结果保留在 stage_details.docs.files（init 中位于 sync 下）。替换外来内容需要批准，并保留同级备份。详见响应契约。

配置

~/.fx 保存工作区注册、个人层、资源所有权状态、信任和缓存。FX_HOME 只改变 fx 的个人目录，不改变配套工具的凭据位置。

config list 展示配置键、默认值、环境变量名及实际来源；config get <key> --explain 展示各层。优先级为显式参数、环境变量、配置文件、内置默认值。用 config export/import 迁移个人设置。

导入按名称合并工作区注册，保留 profile 中未提到的工作区；明确列出的个人层会被替换。导入不会改变已有工作区的根目录或来源，请先使用 workspace relocate 或 workspace rebind。用 workspace unregister 明确解除托管。计划会列出注册情况和仍需完成的准备步骤；缺失的 manifest checkout 可通过输出的 init 命令恢复。导出不复制 manifest checkout、信任或凭证。

format 控制输出。command_shell 只控制生成命令的文本，不改变执行方式；auto 在 Windows 选择 PowerShell，其他平台选择 POSIX。可用 --command-shell、FX_COMMAND_SHELL 或 cmd 配置覆盖。manifest 中的 shell 模板保持原样。

补全支持 bash、zsh、fish 和 PowerShell，通过 fx completion <shell> 生成，按需自行加载。

Agent 选择

fx config set agents codex 选择指定宿主，fx config set agents '' 或空 FX_AGENTS 选择无宿主。取消配置和环境覆盖后恢复检测。Agent 选择影响同一 FX_HOME 的全部工作区；FX_HOME 不迁移全局 Skill 或配套工具凭证。

集成

manifest 选择工作区使用的 provider 和配套 CLI。fx manifest providers 列出本工作区中每项能力绑定了什么；fx tool list --catalog 列出 fx 已知的全部配套工具，包括这里没有被选用的。通讯和知识入口交接给配套工具，不代表 fx 代理了所有服务 API。

Agent 发现包括 Claude Code、Codex CLI、Cursor 等已注册宿主。Skill、hook、MCP 与规则的支持因宿主而异；用 agent list、hook list、mcp list 检查具体能力，不要假定各宿主功能一致。

判读初始化与恢复结果

按结果返回的继续操作处理。新来源尚未被接受时，使用完整的原始重试命令；否则续跑读取托管来源和现有选择。注册与文件写入只是已发生的效果，完成判定看 preparation.state 和阻塞项。

本地预览检查目录、stdin 或 Git 已提交内容；新的远端来源在获取前保持 source_inspected: false。已知指南冲突与计划命令会先展示，预览不授予信任。普通源指南会在生成的目标中补齐 fx 区域，保留共享源正文；模糊标记交给维护者修正。

部分失败会保留已完成仓库、本地准备和用户文件。补齐列出的前置条件后，按返回动作继续；已有安装和通过验证的步骤会跳过。相对验证文件以工作区根为基准。含空格或 Unicode 的目录会自动生成名称，直接使用返回的身份即可。

遇到 SKILL_WRITE_DENIED 先处理被拒绝的路径；改变 FX_HOME 不会移动全局锁。可用 fx sync --only repos,docs --no-refresh-manifest 继续允许的工作，但不能声称 Skill 已修复。外来文件替换仍需批准并保留备份。Git 来源刷新保留本地修改，普通重试重新检查仓库可读性。详见支持。

人工接手后恢复登录

使用 doctor --tool <name> 定向诊断时, 只检查或修复指定工具的安装与准备状态, 不刷新无关仓库、指引或宿主资源. 省略 --tool 可检查整个工作区. 客户端启动或版本检查失败时, 依赖它的命令检查会等待该前置条件; 这不表示需要重新登录.

can 和启用检查的 where 返回已检查工具的 execution.binary_path、version 和 cwd. 后续调用使用这个路径和工作目录, 避免新 shell 从 PATH 选中其他安装. Provider 命令与直接 handoff 命令已绑定路径; manifest 自定义 shell 模板仍按原文输出. tool install/update 同时返回 binary_path 与 version_after. 更新后重新检查就绪并加载匹配的伴生 Skill.

准备就绪不代表拥有每项 API 权限. 先验证所需操作再补权: 搜索失败不能证明已知文档无法读取. 不支持设备 OAuth 的 Sentry 实例可声明 service.auth_scheme: token, 改为人工设置个人 Token; 已有效的 CLI 登录仍可复用. 不要将 Token 写进 manifest 或聊天.

login 需要人工输入时，先完成已授权的 handoff，再重跑同一命令。fx 会先检查当前状态，再决定是否重复操作；随后重新执行原先的 can 或 doctor 检查，继续原任务。与 init 和 sync 一样，login 会直接运行复用已有登录的内置步骤，即使带 --no-input 也不询问；只有登录前才会询问。

机器调用方在非零退出时也要同时读取部分 stdout 与 stderr 错误。已完成步骤仍保留；handoff、blocked、failed、not_started 区分后续工作。汇总、计划问题和步骤恢复字段见登录响应契约。

交给人处理的步骤会说明它的检查得到了什么回答。步骤的 check 带有工具自己的信息；fx 能读懂失败原因时还会给出成因：未能建立认证、服务拒绝了权限，或连接未能建立。此时步骤的说明针对该成因给出处理办法，重新登录前请先阅读。多数检查不给出成因，这时以工具的信息和步骤的说明为准。

没有得到回答的检查（工具没能启动，或超时）不会交给人处理。can 与 where 把它列在 unfinished 中，没有其他失败时返回 unknown；login 以该错误停止，并在 stdout 保留部分结果；doctor 把它报告为覆盖不完整的检查项。较早版本的 fx 没有这些字段；fx doctor --tool <tool> --env <env> 可查看单个工具给出的信息。

Skill 所有权与宿主激活

用户级 fx Skill 跨工作区共享，并由用户级锁保护；团队链接属于各自工作区，配套安装器管理自己的版本行为。文件正确不证明宿主已激活。

用 hook list 查看支持和验证状态。已测试的 Grok 1.0.25 仅在 Git 根发现项目 hook，普通目录信任不能解除此限制。使用显式 fx sync --only docs,skills，保持工作区根为普通目录；宿主执行审批仍独立生效。

复用已有登录

初始化会保留团队统一的 context 名称。兼容的配套 CLI 会先匹配同一服务的已有登录，复用个人身份，再决定是否需要你登录。Token 继续保存在原 CLI 的凭据存储中，当前 context 和已有身份保持不变。多个身份匹配时，可使用原 CLI 的 auth reuse --from-context 选择来源；网络或钥匙串问题会与缺少凭据分开报告。多个环境可能共享已保存的登录：fx login 为其中一个环境完成登录后，会重新检查该工具之前未能完成的环境，并把已经可用的报告为 verified。

成员归属与业务协作

用 fx member selectors 发现筛选值, 可用 --kind area、scenario、team 或 function 限定类型. 每行返回类型、ID、名称和所属 area, 不列出人员. 把场景误填为 area 时, 错误会给出正确父级的完整查询. 缺失账号字段仍表示未知. 职责数据可支持分派建议, 不授权覆盖既有工作项负责人.

使用 fx member show <account> --system <system> --area <id> --format json 查询作者。确认身份需要唯一的精确账号匹配。分别读取目录归属、业务责任团队和个人协作职责。多支团队可以同时得到确认。候选关系仍需核实，未覆盖的归属保持未知。省略业务域会返回所有适用关系。

使用 fx member list --team <id> --function <id> --area <id> 查找承担该项工作的人。所有条件必须命中同一条协作关系。省略业务范围时也可匹配目录关系。--as-of YYYY-MM-DD 按指定日期检查声明的有效期。