profile

管理共享的 Apothem 配置档案。

profile 是一个命令组，包含四个子命令：init、show、set 和 edit。共享配置档案是唯一的事实来源，每个工具适配器都会将它物化为各自的原生配置。

概要Copy Anchor Link

apothem profile init [--profile PATH] [--force]
                     [--quiet|-q] [--verbose|-v]
                     [--format plain|json] [--json] [--no-color]
apothem profile show [--profile PATH] [--quiet|-q] [--verbose|-v]
                     [--format plain|json] [--json] [--no-color]
apothem profile set KEY VALUE
                     [--profile PATH] [--quiet|-q] [--verbose|-v]
                     [--format plain|json] [--json] [--no-color]
apothem profile edit [--profile PATH] [--quiet|-q] [--verbose|-v]
                     [--format plain|json] [--json] [--no-color]

通用选项Copy Anchor Link

每个子命令都接受下列共享选项。

子命令Copy Anchor Link

profile initCopy Anchor Link

在 ~/.config/apothem/profile.yaml 或 --profile PATH 处创建一个符合模式的最小配置档案脚手架。除非提供了 --force，否则现有文件会被保留。

脚手架的第一行是一条 yaml-language-server modeline 指令，指明配置档案模式的 $id，即 https://apothem.ahmedgad.com/schemas/profile.schema.json。本站在该地址提供打包的模式，因此支持 YAML 语言的编辑器会在你编辑配置档案时对其进行校验。src/apothem/schemas/ 下的每个打包模式都以同样的方式在 https://apothem.ahmedgad.com/schemas/<file> 提供。

profile showCopy Anchor Link

显示经过校验、默认值已展开的共享配置档案。使用 --json 时，输出的文档就是配置档案本身，以 schema_version 开头：即引擎读取该配置档案时所依据的配置档案模式版本（参见 JSON 输出契约）。

profile set KEY VALUECopy Anchor Link

在共享配置档案中设置一个键。KEY 是一个点分路径，会逐层深入嵌套的配置档案（identity.name、preferences.style、enforcement.sprints、harnesses.<harness>.preferences.style）；不含点的单个键设置一个顶层节点。VALUE 作为字面字符串存储——裸词不会被强制转换（no 保持为 "no"，2024-01-01 和 1.0 保持为字符串）——但 true/false（布尔型强制执行标志）以及显式的 [...]/{...} 列表/映射输入除外。在写入之前，完整组装后的配置档案会依据模式进行校验；无效的设置会被拒绝，磁盘上的配置档案保持不变。

profile editCopy Anchor Link

在系统编辑器中打开共享配置档案。

校验错误Copy Anchor Link

每个读取配置档案的命令都会依据打包的模式对其进行校验，并一次性报告它发现的每一个问题，因此一次编辑即可将它们全部修复：

• 纯文本输出完整给出第一个问题（Field、Reason、Fix 和 Offending value (redacted)：未通过校验的输入，其中形似机密的值被替换为 <redacted>；它绝不是建议的替换值），然后在 Other problems 下再列出最多十个问题。
• JSON 输出将第一个问题保留在 error 对象的顶层字段中，并添加一个包含每个问题的 errors 数组（code、field、reason、fix、safe_value）。
• 未知键只回显这个意外的键及其经过脱敏的值，而不是整个配置档案。
• 受管块标记。 任何键或文本值都不得包含 <!-- BEGIN APOTHEM MANAGED BLOCK --> 或 <!-- END APOTHEM MANAGED BLOCK -->。Apothem 会在指令文件中围绕它所管理的块写入这些标记，而配置档案文本会落在该块内部，因此其中出现的标记会把该块拆开。每个这样的字段都会以 profile.managed_block_marker 失败：field 是它的点分路径（例如 rules.2 或 mcp_servers.search.env.SEARCH_MODE），reason 指明该标记。值本身绝不会被回显（safe_value 为 null），因为它可能是一项凭据。

profile init（以及其他每个生成配置档案脚手架的命令）会写入 schema_version: 1。不含 schema_version 的配置档案按版本 1 读取。

示例Copy Anchor Link

apothem profile init
apothem profile init --profile ./profile.yaml --force --json
apothem profile show
apothem profile show --json
apothem profile set seriousness SHARED
apothem profile set rules '["Use fake placeholders in examples."]'
apothem profile edit

退出码Copy Anchor Link

另请参阅Copy Anchor Link

• apothem install——将配置档案物化到一个工具中
• apothem doctor——运行系统级的安装诊断