Phases Agents

phases-agents

English · Français

一个本地 MCP 服务，可确定性地发现、验证和选择技能。仅使用 Python 标准库，无运行时依赖。

一个服务。五个工具。绝不在你不知情的情况下执行任何操作。

原因

AI Agent 会即兴发挥。同一个问题问两次，就会得到两个不同的计划。头脑风暴时这没问题，但审计和合规工作绝不能接受。

phases-agents 消除了即兴发挥。它会分析本地项目，根据严格的契约验证技能目录，并返回可重放的计划。目标相同、目录相同、参数相同，决策也相同。

原则

configured root identifiers
→ bounded discovery
→ official validation
→ immutable registry
→ verified cache
→ detector profile
→ deterministic selection
→ MCP plan

服务负责选择并公开技能。调用方模型读取选中的技能，并使用自己的工具决定如何处理它们。服务绝不执行技能。

架构

模块位于 src/phases_agents/。

文件	作用
validator.py	官方契约和经过验证的快照
skill_loader.py	有界的本地发现
skill_runtime.py	可信根目录和已验证缓存
skill_types.py	不可变类型和限制
registry.py	经过验证的不可变注册表
detector.py	目标的本地分析
planner.py	确定性的选择和排序
server.py	JSON-RPC/MCP 传输
capabilities.py	客户端能力词汇表
profile_facts.py	版本化的配置事实词汇表
skill_gaps.py	缺口规则（skills_missing）

规范性契约位于 src/phases_agents/core/SKILLS_CONTRACT.md（法语）。

快速开始

示例包位于 examples/skills/。只需三步即可生成实际计划。

git clone https://github.com/Cherridsaid/phases-agents && cd phases-agents

创建 skills-roots.json，指向示例根目录：

{
  "config_version": "1.0",
  "roots": [
    { "id": "demo", "path": "/absolute/path/to/phases-agents/examples/skills" }
  ]
}

pip install -e .
phases-agents --skills-config /absolute/path/to/skills-roots.json

pip install -e . 会安装 phases-agents 命令。无需安装时，可通过 PYTHONPATH=src python -m phases_agents.server 启动同一个服务。

服务逐行读取标准输入中的 JSON-RPC。对 Python 项目调用 phases_agents_plan 后，会选择 hello-python：

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"phases_agents_plan",
 "arguments":{"root_ids":["demo"],"target":"/absolute/path/to/a/project",
 "today":"2026-08-27","plan_version":"B3",
 "client_capabilities":["filesystem_read","filesystem_search"]}}}

两种计划格式并存。"B3" 指版本化的格式，而非服务版本；其官方架构为 src/phases_agents/core/PLAN_B3_SCHEMA.json。新工作请使用此格式。如果未指定 plan_version，则会返回由步骤组成的扁平列表的旧版格式；保留该格式是为了不影响现有调用方，并将在移除前弃用。client_capabilities 仅在 B3 中接受，因为只有在该格式下，声明客户端能做什么才有意义。

连接 MCP 客户端

Claude Code（项目根目录中的 .mcp.json）：

{
  "mcpServers": {
    "phases-agents": {
      "command": "phases-agents",
      "args": [
        "--skills-config",
        "/absolute/path/to/skills-roots.json"
      ]
    }
  }
}

Codex 在自己的配置文件中使用相同的命令/参数组合。无需令牌，也无需环境变量。

MCP 工具

detect(target)
list_skills(root_ids, today)
get_skill(root_ids, today, skill_id)
plan(root_ids, target, today, constraints?)
plan(root_ids, target, today, plan_version, client_capabilities?)
refresh_skills(root_ids, today)

today 是注入的，而非从时钟读取，因此每次调用都可重放。get_skill 接受标识符，而非路径；其内容来自经过验证的快照。公开输出中的绝对路径和检测到的机密都会被屏蔽。任何编码后的 JSON-RPC 响应都不会超过 1 MiB。

首次调用会构建经过验证的注册表。后续调用会验证元数据，而不重新读取内容。refresh_skills 会强制重建。

编写技能包

每个包都是根目录的直接子项，且至少包含：

<root>/<skill-id>/SKILL.md
<root>/<skill-id>/phases.json

最快的入门方式是复制 examples/skills/hello-python/，然后重命名标识符。

SKILL.md frontmatter

允许使用五个键。全部为可选项，存在时均会检查。

键	限制
name	必须与 phases.json.id 相同
description	长度受限的自由文本
version	必须与 phases.json.version 相同
owner	自由作者身份，不得包含不可见字符
license	Apache-2.0、MIT、BSD-2-Clause 或 BSD-3-Clause

十四个必需章节

每个章节都必须是 Markdown 标题（##），顺序不限。章节标题为法语， 因为它们属于契约；正文可使用任意语言撰写。

Loi centrale · Ce que ce skill fait · Ce que ce skill ne fait pas · Conditions d'activation · Conditions d'exclusion · Capacites necessaires · Interdictions · Methode d'audit · Contrat de preuve · Format de sortie · Conditions de blocage · Limites connues · Exemples d'entree · Exemple de sortie attendue

phases.json 字段

以下字段均为必需：schema_version、id、version、title、description、 domain、project_types、platforms、activation、exclusions、 requires_capabilities、optional_capabilities、forbidden_capabilities、 execution_mode、human_approval、output_schema、rules_path、 references_path、scripts_path、tests_path、files。

output_schema 使用符号形式 core:SCHEMA_NAME.json。

封闭词汇表

project_types 必须与检测器可能输出的类型有交集：apk、python、 skill_package、solana、web。

activation.any 使用配置文件事实：collects_personal_data、has_api、 has_apk、has_authentication、has_database、has_ecommerce、 has_eu_context、has_file_upload、has_javascript、has_python、 has_rust、has_skill_packages、has_solana、has_source_code、 has_typescript、has_web、uses_ai、uses_payments。

requires_capabilities、optional_capabilities 和 forbidden_capabilities 使用：browser、dependency_installation、 filesystem_read、filesystem_search、filesystem_write、human_question、 shell、target_code_execution、web。

提供的能力使用开放词汇表：每个目录列出其提供的内容，系统只检查格式是否符合 ^[a-z][a-z0-9_]{0,63}$。只有客户端能力使用封闭词汇表，因为它们描述的是协议， 而非你的领域。

domain 为 legal、juridique、regulatory 或 compliance 时，将触发额外规则： 引用的每条规则都必须附有官方来源、司法管辖区和验证日期。

架构的说明范围

SKILL_MANIFEST_SCHEMA.json 描述 phases.json 的结构： 必需字段、类型和封闭词汇表。

架构引擎刻意保持精简。它只应用 enum、minLength 和 minItems，不做其他处理： 不支持 pattern、if/then 或 oneOf。使用这些关键字的架构本身也会被拒绝。

因此，条件规则由 validator.py 处理，它仍是真正的依据。版本规则就是一个例子： 在 1.0 清单中，禁止使用 provides_capabilities；在 1.1 清单中，该字段为必需项。 此规则已实施并经过测试，但无法在架构中表达。不要将 required 理解为完整契约。

仅包含 SKILL.md 的包会验证失败。无效包会阻止注册表构建，而非被静默降级。

Identity

phases.json.id 是身份标识，且 SKILL.md.name 必须与之匹配。目录必须使用相同的键。 键会先经 NFKC 规范化，再进行 casefold 处理，因此无法利用形近字符伪造第二个身份。 任何冲突都会阻止整个构建；系统不会任意选定某个包。

选择

注册表中的每项有效技能都会归入且仅归入一个类别，并附上理由。不会悄无声息地丢弃任何内容。

唯一经过验证的自动信号是：

project_types ∩ profile.types

只有调用方提供平台、领域和能力约束时，这些条件才会用于筛选。存在禁止能力的技能会被拒绝。不会臆造语义评分，计划会按标识符排序。

空计划明确有效：它包含 NO_COMPATIBLE_SKILL。

B3 计划会将每项已安装技能分类到 skills_selected、skills_not_applicable 和 skills_blocked 之一；每项技能只会出现一次。skills_missing 列出没有可执行提供方的能力，且仅根据已确认的事实得出。差距绝不能证明不合规：它表示必要的审计尚未覆盖相关内容。

限制

• 最多 16 个根目录
• 仅限直接深度
• 最多 1,000 个包
• 每个根目录最多 10,000 个条目
• SKILL.md 上限为 256 KiB
• 单个引用上限为 256 KiB，总计 1 MiB
• 快照上限为 16 MiB
• 公开结果上限为 1 MiB
• 每个包最多 100 个问题
• 指纹上限为 100,000 个节点

调用方只能降低这些限制，不能提高。

运行时约束

• Python >=3.11
• 不依赖第三方运行时依赖
• 不进行隐式网络访问
• 不使用运行时 shell
• 不执行目标代码
• 不隐式读取时钟
• 不收集遥测数据
• 不下载技能

pytest 仅是开发依赖。

测试

python -m pytest -q

预期结果：各平台均收集到 778 项测试，0 项失败：

Linux           : 771 passed, 7 skipped
Windows (CI)    : 778 passed, 0 skipped
Windows (local) : 776 passed, 2 skipped

跳过的测试与平台能力有关，并非失败。Linux 会跳过 Windows junction 测试，因为 POSIX 没有对应机制。只有在本地缺少创建符号链接的权限时，Windows 才会跳过两项符号链接测试；因此，拥有该权限的运行器不会跳过任何测试。以上所有计数均来自实际运行：两条 Windows 结果分别来自 GitHub Actions 运行器和一台本地计算机。

规范文本会以 LF 换行符检出，并由 .gitattributes 强制执行。少数 Windows 符号链接测试会被跳过：这些测试需要本地 Windows 权限。Windows junction 则会实际进行测试。

证明程度

验证器只确认一件事：

STRUCTURALLY_VALIDATED

它不会验证真实目标。V1 中仍然禁止使用 TARGET_VERIFIED。

安全

加载器会拒绝重解析点。读取范围受限且限定在允许的范围内。输出经过排序且具有确定性。

有一项设计决定值得注意：detect 和 plan 接受一个 target 路径，该路径不受配置根目录的约束，因为其目的就是分析任意项目。请在权限范围符合你接受程度的账户下运行此服务，并且只连接到可信客户端。完整的威胁模型见 SECURITY.md。

不作保证

• 不保证普遍适用的语义相关性
• 不会自动批准外部技能
• 不审计脚本内容
• 不保证目标确实已挂载
• 不保证 Windows 上完全原子化
• 不保证普遍识别 HTML
• 不保证普遍检测机密
• 不保证符合法律要求
• 无市场，无远程来源

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。