aifp

AIMFP：AI 模块化函数式过程编程

一种与编程语言无关的编程范式，专为 AI 生成和维护的代码库设计

---

目录

• 什么是 AIMFP？
• 核心原则
• 架构概览
• 数据库架构
• 工作原理
• 快速开始
• 平台支持
• 指令系统
• 项目生命周期
• 工作流示例
• 文档
• 开发
• 设计理念
• 功能
• 使用示例
• 隐私政策
• 支持
• 许可证

---

什么是 AIMFP？

**AIMFP（AI 模块化函数式过程编程）**是一种结合了以下特点的编程范式：

• 纯函数式编程原则（引用透明性、不可变性、可组合性）
• 过程式执行模式（显式排序、无隐藏状态）
• 数据库驱动的项目管理（持久化状态、即时上下文检索）
• 基于指令的 AI 指导（确定性工作流、自动化合规）

使用 AIMFP 的两种方式

用例 1：常规软件开发

• 构建应用程序（Web 应用、库、CLI 工具等）
• AIMFP 强制遵循函数式编程规范并管理项目
• 你编写代码，AI 协助遵循函数式编程标准并跟踪项目
• 示例：构建 Web 服务、计算器库、数据处理器

用例 2：自定义指令自动化

• 定义自动化规则（家庭自动化、云管理、工作流）
• AIMFP 为你生成并管理自动化代码库
• 你编写指令定义（YAML/JSON/TXT），AI 生成实现
• 项目代码本身就是根据你的指令生成的自动化代码
• 示例：智能家居控制系统、AWS 基础设施管理器、工作流自动化工具

核心原则：每个项目目录使用一个 AIMFP 实例。不要将 Web 应用与家庭自动化指令混用。不同用途应运行独立实例。

为什么选择 AIMFP？

传统编程范式是为人类设计的。AIMFP 针对 AI 与人类协作进行了优化：

挑战	传统方法	AIMFP 解决方案
上下文丢失	AI 在会话间会遗忘	数据库驱动的持久化状态
OOP 复杂性	类、继承、多态	纯函数、显式数据结构
无限期开发	项目永远无法“完成”	通过里程碑设定有限的完成路径
代码推理	反复解析源代码	预先索引函数、依赖关系和交互
标准不一致	风格指南、代码检查、评审	通过不可变指令强制遵循规范

---

核心原则

1. 函数式与过程式混合

# ✅ AIMFP-Compliant
def calculate_total(items: List[Item]) -> float:
    """Pure function: deterministic, no side effects"""
    return reduce(lambda acc, item: acc + item.price, items, 0.0)

# ❌ Not AIMFP-Compliant
class Calculator:
    def __init__(self):
        self.total = 0  # Hidden state

    def add_item(self, item):
        self.total += item.price  # Mutation

2. 数据库索引的逻辑

每个函数、文件和依赖项都在 SQLite 中进行跟踪。AI 通过辅助工具访问这些数据，而不是直接使用 SQL：

AI calls: get_functions_by_file(file_id)
→ Returns: all functions in that file with name, purpose, parameters, returns

无需重新解析源代码，即可在不同会话间即时检索上下文。

3. AI 易读的代码

• 扁平结构：没有深层继承层次
• 显式依赖：所有参数均显式传递
• 纯函数：相同输入 → 相同输出
• 元数据注释：机器可读的函数头部

4. 有限的完成路径

Project: MatrixCalculator
├── Completion Path (3 stages)
│   ├── 1. Setup (completed)
│   ├── 2. Core Development (in progress)
│   │   ├── Milestone: Matrix Operations
│   │   │   ├── Task: Implement multiply
│   │   │   ├── Task: Implement transpose
│   │   │   └── Task: Add validation
│   │   └── Milestone: Vector Operations
│   └── 3. Finalization (pending)

5. 与编程语言无关

AIMFP 适用于 Python、JavaScript、TypeScript、Rust、Go 等语言。函数式编程指令会适配特定语言的语法，同时保持通用标准。

---

架构概览

┌─────────────────────────────────────────────────────┐
│            AI Assistant (Claude, GPT-4, etc.)        │
│  - Receives natural language commands                │
│  - Follows directives (FP baseline + project mgmt)   │
│  - Calls MCP tools to read/write databases           │
│  - Generates FP-compliant code                       │
└────────────────────┬────────────────────────────────┘
                     │ MCP Protocol (JSON-RPC over stdio)
┌────────────────────▼────────────────────────────────┐
│                 MCP Server                           │
│  - Exposes helper tools via JSON-RPC                  │
│  - Manages four-database connections                 │
│  - Provides CRUD helpers for all databases           │
│  - No business logic — AI makes all decisions        │
└───┬────────────────────┬─────────────────────────┬──┘
    │                    │                         │
┌───▼──────────────┐ ┌───▼────────────────┐ ┌─────▼─────────────────┐ ┌──────▼────────────────┐
│  aimfp_core.db    │ │  project.db        │ │  user_preferences.db  │ │  user_directives.db   │
│  (Global,        │ │  (Per-Project,     │ │  (Per-Project,        │ │  (Per-Project,        │
│   Read-Only)     │ │   Mutable)         │ │   Mutable)            │ │   Optional)           │
│                  │ │                    │ │                       │ │                       │
│ - FP directives  │ │ - Project metadata │ │ - Directive prefs     │ │ - User directives     │
│ - Project mgmt   │ │ - Files & funcs    │ │ - User settings       │ │ - Execution stats     │
│ - User prefs     │ │ - Task hierarchy   │ │ - AI learning log     │ │ - Dependencies        │
│ - User systems   │ │ - Themes & flows   │ │ - Tracking features   │ │ - Generated code refs │
│ - Helper defs    │ │ - Completion path  │ │ (All opt-in)          │ │ - Source file tracking│
│ - Directive flow │ │ - Runtime notes    │ │                       │ │ (Logs in files)       │
└──────────────────┘ └────────────────────┘ └───────────────────────┘ └───────────────────────┘

用例 2 增加了第二条完全不经过 MCP 服务的路径。 自动化必须在没有 AI 会话开启时运行，因此它会将 AIMFP 作为普通库导入：

┌──────────────────────────────┐        ┌──────────────────────────────┐
│  cron / systemd / your daemon │        │  AI Assistant (a session)     │
│  runs forever; AIMFP does not │        │  present only when you are    │
└───────────────┬──────────────┘        └───────────────┬──────────────┘
                │ starts                                 │ MCP
┌───────────────▼──────────────┐        ┌───────────────▼──────────────┐
│  runner.py  (YOUR project)    │        │         MCP Server            │
│  generated by AIMFP, owned    │        │                               │
│  and editable by you          │        │  check_directive_health       │
│                               │        │  get_directive_execution_stats│
│  import aimfp.hooks  ◄────────┼── a    │  get_recent_directive_errors  │
│  get_due_directives(...)      │  library                              │
│  run_directive(...)           │  call, └───────────────┬──────────────┘
└───────────────┬──────────────┘  not RPC               │ reads
                │ writes                                 │
                └────────────►  user_directives.db  ◄────┘
                                + .aimfp-project/logs/

运行器负责写入；AI 稍后再读取。AIMFP 本身在此期间不会执行任何操作——它没有计时器，也不会启动任何任务。

---

数据库架构

aimfp_core.db（全局，只读）

位置：位于 MCP 服务安装目录中（用户定义的位置，在 AI 客户端中配置）

用途：不可变知识库，包含所有 AIMFP 标准、指令和辅助函数定义。

主要表：

• directives：所有 FP、项目和用户偏好指令（工作流、关键词、阈值）
• helper_functions：按多个注册表文件分类整理的数据库、文件、Git 和 FP 工具
• directive_helpers：多对多联结表，将指令映射到辅助函数，并包含执行元数据
• categories：指令分组（纯函数性、不可变性、任务管理等）
• directive_flow：由状态驱动的指令导航和路由

辅助函数与指令的关系（v1.4 新增）：

• 一个指令可以使用多个辅助函数，一个辅助函数也可以服务于多个指令
• 联结表存储：执行上下文、顺序、参数映射
• 支持灵活复用辅助函数，并明确执行流程
• 在 aimfp_core.db 的 directive_helpers 联结表中定义

辅助函数分类：

• 工具：所有辅助函数都作为 MCP 工具公开（AI 通过 MCP 直接调用）
• 子辅助函数（is_sub_helper = TRUE）：仅由其他辅助函数调用的内部工具（不向 AI 公开）

辅助函数注册表（开发暂存）：

• 开发期间，辅助函数定义保存在 dev/helpers-json/*.json 中
• 开发者修改 JSON 文件，完成后再导入数据库
• 每个辅助函数都包含 used_by_directives 字段，用于关系映射
• 发布前，数据库导入脚本会使用 JSON 文件填充 aimfp_core.db
• 生产环境：用户查询预先填充数据的 aimfp_core.db，而非 JSON 文件
• JSON 文件仅用于开发暂存，不会随软件包发布

只读原则：此数据库纳入版本控制，部署后不可变。AI 可以读取其中的数据，但不能修改。

project.db（每个项目独立，可变）

位置：<project-root>/.aimfp-project/project.db

用途：单个 AIMFP 项目的持久状态。跟踪代码结构、任务和运行时备注。

主要表：

• project：高级元数据（名称、用途、目标、状态、user_directives_status、last_known_git_hash）
• files、functions、interactions：代码结构跟踪
• themes、flows：组织分组
• completion_path、milestones、tasks、subtasks、sidequests、items：分层路线图
• task_files：每个任务/子任务/支线任务所涉及的文件——条目进行期间自动关联
• modules、module_files、file_flows：可复用的代码边界以及文件到流程的分配
• notes：运行时日志记录，可选包含指令上下文（来源、严重程度、directive_name）
• types：代数数据类型（ADT）
• infrastructure：项目设置（语言、软件包、测试）
• work_branches：Git 协作元数据（用户、用途、合并策略）
• merge_history：由 FP 驱动的合并冲突解决审计记录

用户指令集成：project.user_directives_status 字段用于跟踪用户指令是否已初始化（NULL/in_progress/active/disabled），使 aimfp_run 和 aimfp_status 指令能够在用户指令启用时包含其上下文。

增强备注：notes 表现在包含 source（user/ai/directive）、directive_name（可选上下文）和 severity（info/warning/error），以便更好地追踪。

user_preferences.db（每个项目独立，可变）

位置：<project-root>/.aimfp-project/user_preferences.db

用途：存储用户专属的 AI 行为自定义设置和选择加入的跟踪功能。

主要数据表：

• directive_preferences：每条指令的行为覆盖设置（原子键值结构）
• user_settings：项目范围的 AI 行为设置
• tracking_settings：选择加入的跟踪功能标志（默认全部禁用）
• ai_interaction_log：用户纠正和学习数据（选择加入）
• fp_flow_tracking：FP 合规历史（选择加入）
• issue_reports：上下文错误报告（选择加入）

成本管理理念：默认禁用所有跟踪功能，以尽可能减少 API 令牌用量。项目工作应注重成本效益；调试和分析功能均需选择加入。

用户自定义示例：

-- User says: "Always add docstrings"
INSERT INTO directive_preferences (directive_name, preference_key, preference_value)
VALUES ('project_file_write', 'always_add_docstrings', 'true');

-- Next file write automatically includes docstrings

user_directives.db（每个项目独立，可选）

位置：<project-root>/.aimfp-project/user_directives.db

用途：存储用户定义的领域专用自动化指令（例如家庭自动化、云基础设施等）。存在此数据库时，AIMFP 项目即专门用于构建和管理根据这些指令生成的自动化代码。

此数据库仅存在于用例 2：自定义指令自动化项目中。在常规软件开发项目中，不会创建此数据库。

主要数据表：

• user_directives：指令定义（触发器、操作、状态、已验证的配置）。trigger_config 和 action_config 遵循强制语法，详见指令配置架构
• directive_executions：执行统计信息（仅摘要，详细日志存储在文件中）
• directive_dependencies：所需的软件包、API、环境变量
• directive_implementations：将指令关联到生成的代码文件
• helper_functions：AI 生成的辅助函数（项目专属实现工具）
• directive_helpers：多对多关联表，将用户指令映射到其辅助函数
• source_files：跟踪用户指令源文件（YAML/JSON/TXT）
• logging_config：基于文件的日志配置

辅助函数（v1.0 新增）：

• AI 为用户指令生成项目专属辅助函数
• 跟踪实现状态：not_implemented → generated → tested → approved
• 对所有生成的代码强制执行 FP 合规要求（纯函数）
• 与 aimfp_core.db 使用相同的多对多关系模式

基于文件的日志理念：数据库仅存储状态和统计信息。详细执行日志（保留 30 天）和错误日志（保留 90 天）存储在 .aimfp-project/logs/ 下的轮转文件中。

目录结构对比：

# Use Case 1: Regular Software Development
my-web-app/
├── src/                    # Your application code
├── tests/                  # Your tests
└── .aimfp-project/          # AIMFP tracks your application
    ├── project.db
    └── user_preferences.db

# Use Case 2: Custom Directive Automation
home-automation/
├── directives/             # ← User writes directive files here
│   ├── lights.yaml
│   └── security.yaml
├── src/                    # ← AIMFP GENERATES this code
│   ├── lights_controller.py
│   ├── security_monitor.py
│   └── runner.py           # ← the RUNNER: your scheduler calls this,
│                           #    it imports aimfp.hooks as a library
├── tests/                  # ← AIMFP GENERATES tests
└── .aimfp-project/          # ← AI-managed only, user never touches
    ├── project.db          # Tracks generated src/ code
    ├── user_preferences.db
    ├── user_directives.db  # References ../directives/ files
    └── logs/               # 30/90-day execution logs

# ...and outside the project entirely:
/etc/cron.d/home-automation  # ← what actually STARTS runner.py. Not AIMFP.

工作流示例（自动化项目）：

1. 用户在其项目中创建 directives/lights.yaml
2. 用户告诉 AI：“解析我的指令文件 directives/lights.yaml”
3. AI 通过交互式问答进行解析和验证
4. AI 在 src/ 中生成符合 FP 要求的实现代码
5. AI 在 project.db 中跟踪生成的代码（文件、函数、任务）
6. AI 生成运行器，并接入你的调度器（cron、systemd 或守护进程循环）
7. 你的调度器运行这些指令——AIMFP 没有计时器，也不会在凌晨 3 点运行
8. 运行器通过 aimfp.hooks 记录每次执行；日志写入 .aimfp-project/logs/，统计信息写入 user_directives.db
9. 下次会话时，AIMFP 会报告发生的情况以及可能出问题的地方

注意：用户指令文件保留在用户的项目中。.aimfp-project/ 是由 AI 管理的元数据。

指令配置架构

触发器和操作采用强制语法。不符合要求的配置会在插入时被拒绝——不当的操作会在运行时明确报错，但不当的计划会因永不触发而静默失败，因此两者都会在存储前进行检查。

触发器——时间触发器是基于 kind 的判别联合：

{"kind": "interval", "seconds": 900}
{"kind": "daily",    "at": "17:00", "timezone": "America/New_York"}
{"kind": "weekly",   "at": "17:00", "weekdays": ["mon","wed","fri"]}
{"kind": "monthly",  "at": "09:00", "days": [1, 15]}

{"event": "stove_on", "source": "home_assistant"}              // event
{"expression": "cpu > 90", "evaluate_every_seconds": 60}       // condition (fires once per rise)
{"expression": "cpu > 90", "repeat": "while_true"}             // condition (fires every true check)
{}                                                             // manual

at 是 24 小时制的 HH:MM，并且必须补零。timezone 是 IANA 名称，不能用于 interval——间隔按经过的秒数计算。未知键会被视为错误，因为计划中的键名拼错本会通过验证，却永远不会触发。

操作——每种 action_type 都有一个封装：

{"endpoint": "/lights/off", "api": "homeassistant", "method": "POST"}  // api_call
{"script": "scripts/backup.sh", "args": ["--full"]}                    // script_execution
{"command": "systemctl restart nginx"}                                 // command
{"function": "handlers.lights.turn_off"}                               // function_call
{"message": "Backup finished", "channel": "ops"}                       // notification

对于 function_call 和 command，AIMFP 只验证封装——函数或可执行文件是否存在于生成的项目中，以及能否实际解析，由你负责检查。

AIMFP 还负责计划的时间计算：aimfp.hooks.schedule.next_fire_time 会计算下一次运行时间（在夏令时边界处保持墙上时钟时间正确），而 record_execution_end 会在每次运行后自动更新 next_scheduled_time。你的运行器无需手动编写日历计算逻辑——两个项目对 17:00 的时间理解不一致，就是这样产生的。

如果你要构建 UI，需要了解一个后果：next_scheduled_time 存储为朴素的本地时间，因为 is_due 会将其与朴素的本地当前时间进行比较。在洛杉矶的机器上，声明为 America/New_York 的 17:00 计划会存储为 14:00。信息并未丢失——声明的时区仍保留在 trigger_config 中——但该列只是一个用于比较的值，而非用于呈现的值。应从 trigger_config 向用户显示计划，绝不要使用 next_scheduled_time，否则他们可能会“修正”本来正确的配置。

AIMFP 从不评估条件，但语法规定了持续满足的条件会以多高频率触发。默认情况下，条件在变为真时触发一次，并在评估结果为假时重新布防；"repeat": "while_true" 则会在每次评估结果为真时触发。运行器通过 set_condition_state 保存这一锁存状态，因此重启不会再次触发仍为真的条件。运行器过晚才到达的时间槽会被跳过，不会补执行，并通过 record_directive_skip 记录。跳过既不算运行，也不算错误；持续跳过的指令会显示为 skipping，而不是错误地显示为 ok。

AI 使用 validate_trigger_config 和 validate_action_config 工具验证配置，这些工具会在返回错误的同时提供预期结构。完整规范可通过 trigger_config_grammar() 和 action_config_grammar() hooks 以数据形式获取。

---

工作原理

1. AIMFP MCP 网关模式

aimfp_run 命令充当网关和提醒机制，而非执行器。它会告知 AI 应用 AIMFP 指令。

每次调用 aimfp_run 都会返回：

{
  "success": true,
  "message": "AIMFP MCP available",
  "guidance": {
    "directive_access": "Directive names cached from session bundle. Query specific directives by name when needed.",
    "when_to_use": "Use AIMFP directives when coding or when project management action/reaction is needed.",
    "assumption": "Always assume AIMFP applies unless user explicitly rejects it."
  }
}

MCP 服务为所有数据库操作提供 CRUD 辅助函数——包括跟踪文件、函数、任务、项目状态、用户偏好，以及（对于用例 2）自动化指令。AI 会在运行时从数据库中发现可用的辅助函数。

AI 决策流程：

1. 用户在请求前加上 aimfp run（或由 AI 自行判断）
2. AI 调用 aimfp_run 工具 → 接收指导
3. AI 判断：这是编码还是项目管理任务？
4. 如果是：检查内存中是否有指令
   • 没有指令？→ 指令名称已从会话包中缓存；需要时按名称查询
   • 有指令？→ 应用适当的指令
5. 如果不是：不应用指令，直接回复

2. 命令流程示例

User: "Help me build a calculator"

AI 处理：

1. 调用 aimfp_run(is_new_session=true) → 接收会话包（指令名称、项目状态、设置、辅助上下文）
2. 根据会话包检查项目状态：缺少 .aimfp-project/ → 项目尚未初始化
3. 调用 aimfp_init 辅助程序（阶段 1：机械设置）
   • 以编程方式创建 .aimfp-project/ 目录、数据库和蓝图模板
4. 进入阶段 2（智能填充）：检测语言和工具，与用户讨论项目
5. 路由到 project_discovery：与用户协作制定蓝图、主题、流程、完成路径和里程碑
6. 完成发现 → 路由到 aimfp_status → project_progression → 创建首个任务
7. 开始工作

3. 自我评估框架

采取行动前，AI 使用随指令提供的问题进行自我评估：

核心问题：

1. 这是否涉及编码或项目状态变更？

   • 编码与项目管理已统一——编写代码会自动触发文件跟踪、数据库更新和任务进度更新
   • FP 基线始终生效，是强制性的编码风格
   • 项目指令负责跟踪工作（文件写入、数据库更新、任务管理）

2. 我的内存中是否有指令？

   • 没有：通过 aimfp_run(is_new_session=true) 从会话包加载
   • 有：使用缓存的指令继续

3. 哪些指令适用？

   • FP 基线：强制性的编码风格（纯函数、不可变性、禁用面向对象编程）——自然应用，而不是作为指令调用
   • FP 指令：仅供参考的文档——在复杂场景不确定时查阅
   • 项目指令：文件写入、数据库更新、任务管理

4. 是否需要执行动作-反应？

   • 写入代码 → project_file_write 指令 → 数据库更新
   • 编辑文件 → 数据库同步
   • 讨论并作出决策 → 数据库更新

示例流程（编码任务）：

User: "Write multiply_matrices function"
AI thinks:
  ✓ FP baseline applies (write pure, immutable, no OOP)
  ✓ Project tracking applies (project_file_write directive)
  ✓ I have directives in memory

AI executes:
  1. Write function following FP baseline naturally
  2. Apply project_file_write directive
  3. Update project.db (files, functions, interactions)

4. 指令执行

指令遵循主干 → 分支 → 回退模式：

{
  "trunk": "analyze_function",
  "branches": [
    {"if": "pure_function", "then": "mark_compliant"},
    {"if": "mutation_detected", "then": "refactor_to_pure"},
    {"if": "low_confidence", "then": "prompt_user"},
    {"fallback": "prompt_user"}
  ]
}

---

入门指南

前置要求

• Python 3.11+（项目中使用的类型提示语法所必需；开发和测试覆盖至 3.14）
• Linux——参见下文的平台支持

平台支持

AIMFP 仅在 Linux 上开发和测试。代码库中没有任何平台条件代码，因此对 Windows 和 macOS 的支持是尚未构建，而非未经测试——从未尝试过，要让它们正常运行需要真正的移植工作，而非仅做兼容性检查。

原则上，服务的核心具有可移植性（基于纯标准库的 stdio JSON-RPC、SQLite、pathlib），因此其中部分功能可能恰好能在其他平台上运行。但这一点未经验证，也不受支持。如果你在其他平台上运行 AIMFP，需要自行承担责任——欢迎提交错误报告，但本项目仅以 Linux 为目标环境。

安装

AIMFP 提供三种安装方式。在 Claude Code 上，请使用插件（方法 1）——只需两条命令，无需手动设置。pip/手动安装适用于其他 MCP 客户端或高级配置。

方法 1：Claude Code 插件（推荐用于 Claude Code）

前置条件： 将 uv 添加到 PATH 中（一个独立的二进制文件）。插件通过 uvx 启动 MCP 服务，从 PyPI 获取已发布的 aimfp 软件包、解析其 watchdog 依赖项，并自动安装兼容的 Python（3.11+）——因此，你不需要安装匹配的系统 Python，也无需单独执行 pip install。

/plugin marketplace add aryanduntley/aimfp
/plugin install aimfp@aimfp

就这么简单——无需执行 pip install 或 claude mcp add，也无需配置文件。插件提供：

• MCP 服务，通过 uvx aimfp==<plugin version> 启动——每个插件版本都会运行对应的 PyPI 版本，uvx 会缓存该版本，因此首次启动后即可离线运行；更新插件后，服务也会随之更新
• 斜杠命令：/aimfp:run、/aimfp:status、/aimfp:init、/aimfp:end
• 一个精简的 aimfp-mode 设置技能和一个 SessionStart hook——它们仅用于设置：提示 AI 安装系统提示词（通过 get_system_prompt 工具）并启动会话。它们刻意不包含行为规则的副本（否则会在每个会话中重复加入系统提示词）。安装后的第一步仍然是让 AI 添加 AIMFP 系统提示词——请参阅下文的添加系统提示词；使用插件时，AI 会代你完成，无需下载或粘贴任何内容。
• 会话 hook，用于提醒跟踪写入操作，并在会话结束时进行审计防护

更新方式：/plugin marketplace update aimfp。整个过程无需 Anthropic 账户、审批或中央注册表——此市场就是这个公开的 GitHub 仓库。

插件的 MCP 工具仍需预先批准（工具名称为 mcp__plugin_aimfp_aimfp__*；允许列表涵盖这两种命名方案）——请参阅下文的预先批准所有 AIMFP 工具。

每个项目只选一种方式。 如果项目的 .mcp.json 已注册 aimfp 服务（方式 2/3），安装插件就会启动第二个 AIMFP 服务，导致每个工具都出现两次（mcp__aimfp__* 和 mcp__plugin_aimfp_aimfp__*）。请移除 .mcp.json 中的对应条目，或不要在该项目中启用插件。

方法 2：pip 安装

pip install aimfp

这会安装 MCP 服务，并使 aimfp 命令可用。AIMFP 仅需一个外部依赖项（用于文件系统监控的 watchdog）——JSON-RPC 服务本身使用纯 Python 标准库实现。

方法 3：手动安装（从 GitHub 下载）

1. 下载此仓库（下载 zip 文件或执行 git clone）
2. 找到 src/aimfp/ 文件夹——这是完整的 MCP 服务软件包
3. 复制 aimfp/ 文件夹到你存放 MCP 服务的位置：

   # Example: copy to your MCP servers directory
   cp -r src/aimfp/ ~/mcp-servers/aimfp/
   

唯一的运行时依赖项（watchdog）会自动安装。aimfp/ 文件夹包含服务所需的其他所有内容：辅助函数、指令、数据库架构，以及预先填充数据的 aimfp_core.db。

添加系统提示词（你的第一步）

先做这件事，再做其他任何事。 系统提示词是 AIMFP 的记录管理骨干——它会告诉 AI 首先调用 aimfp_run()，并通过 AIMFP 运行项目。没有它，MCP 工具就只是不会被调用的被动函数；AI 甚至不会知道要启动 init 或发现流程。

推荐——适用于所有安装方式，包括插件（无需下载或粘贴任何内容）。 只需向 AI 提出请求：

Add the AIMFP system prompt

AI 会调用 get_system_prompt 工具，该工具会返回提示词和放置指导，然后替你写入：

• 它会放在项目根目录的 CLAUDE.md（Claude Code）或 Settings → Custom Instructions（Claude Desktop）中。
• AIMFP 内容会放在最前面——它是项目的骨干，必须是优先级最高的指令。
• 如果你已有内容详尽的 CLAUDE.md / 指令文件，AI 不会盲目地将内容插到最前面——它会与你一起审阅，并先讨论如何整合和优化。现有内容绝不会被丢弃。
• 设置完成后，AI 还会询问你是否要配置工具权限允许列表——这是一项一次性设置，可跳过对每个工具的审批提示。它只会预先批准 AIMFP 自带的 CRUD 工具，这些工具严格在 .aimfp-project/ 内操作：不联网、不使用凭据、不访问当前项目之外的任何内容。

手动替代方法（适用于其他 MCP 客户端，或你想自行粘贴的情况）——打印并粘贴到客户端的系统提示词 / 自定义指令字段中：

python3 -m aimfp --system-prompt

AI 客户端	系统提示词的放置位置
Claude Code	项目根目录中的 CLAUDE.md
Claude Desktop	Settings → Custom Instructions
其他 MCP 客户端	系统提示词 / 自定义指令字段

配置 AI 客户端

在 AI 客户端的配置中注册 AIMFP MCP 服务。该服务使用 stdio 传输——从 stdin 读取 JSON-RPC 消息，并将响应写入 stdout。

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "aimfp": {
      "command": "python3",
      "args": ["-m", "aimfp"],
      "env": {}
    }
  }
}

如果你使用的是方法 3（手动安装），请将 aimfp/ 文件夹的上级目录添加到 PYTHONPATH，以便 Python 找到它：

{
  "mcpServers": {
    "aimfp": {
      "command": "python3",
      "args": ["-m", "aimfp"],
      "env": {
        "PYTHONPATH": "/path/to/parent-of-aimfp-folder"
      }
    }
  }
}

例如，如果你将 aimfp/ 复制到了 ~/mcp-servers/aimfp/，请将 PYTHONPATH 设置为 ~/mcp-servers。

如果你安装到了虚拟环境中，请使用该虚拟环境 Python 的完整路径，以确保 Claude Desktop 使用正确的解释器：

{
  "mcpServers": {
    "aimfp": {
      "command": "/path/to/venv/bin/python3",
      "args": ["-m", "aimfp"],
      "env": {}
    }
  }
}

Claude Code

使用 claude mcp add 注册服务。请在你希望 AIMFP 管理的项目文件夹内运行该命令。

先选择作用范围。 AIMFP 会严格执行函数式编程，并主动拒绝面向对象编程的代码库。如果你还会处理采用面向对象编程或不需要 AIMFP 的其他项目，请避免使用 --scope user——它会在你打开的每个项目中启用该服务。

作用范围	效果	适用场景
--scope project（推荐）	在当前目录中创建 .mcp.json。可通过 git 共享。	团队使用及按项目控制
--scope local	按当前目录存储在 ~/.claude.json 中。仅自己可见。	个人按项目使用
--scope user	在你打开的每个项目中均可用。	在所有项目中使用 AIMFP 的开发者

pip 安装（系统范围）：

claude mcp add --transport stdio --scope project aimfp -- python3 -m aimfp

pip 安装（虚拟环境）——使用 venv 的 Python 路径：

claude mcp add --transport stdio --scope project aimfp -- /path/to/venv/bin/python3 -m aimfp

直接使用 python3 会指向系统 Python，而系统 Python 中没有该软件包。请使用 venv 解释器的完整路径，以便 MCP 服务子进程找到已安装的软件包。

手动安装或从源代码运行——将 PYTHONPATH 设置为 aimfp/ 文件夹的父目录：

claude mcp add --transport stdio --scope project --env PYTHONPATH=/path/to/parent-of-aimfp aimfp -- python3 -m aimfp

快速参考：

安装方式	Claude Code 命令
pip install aimfp（系统）	-- python3 -m aimfp
pip install aimfp（venv）	-- /path/to/venv/bin/python3 -m aimfp
手动文件夹 / 从源代码运行	--env PYTHONPATH=/parent/of/aimfp -- python3 -m aimfp

注意：所有标志（--transport、--scope、--env）都必须放在服务名称之前。-- 用于分隔名称和命令。请在 Claude Code 中使用 /mcp 验证服务是否已连接。

Claude Code：预先批准所有 AIMFP 工具（可选）

**这些工具的实际作用：**AIMFP 完全在你指定的项目内运行。它绝不会读取、写入或访问该项目目录以外的任何内容；在项目目录内，它的所有状态都存储在单个 .aimfp-project/ 文件夹中。250 多个工具中的大部分都是针对本地 SQLite 数据库 .aimfp-project/project.db 的简单 CRUD 操作（用于跟踪任务、里程碑、模块和项目状态），以及对内置项目指令的只读查询。它们不会进行网络调用，不需要凭据，也无法访问你更广泛的文件系统。

Claude Code 的设计会在每个 MCP 工具首次调用时提示你批准。250 多个工具意味着每个工具都要进行一次性确认——虽然繁琐，但每次提示都只是 Claude Code 确认一次本地数据库或指令调用。要跳过这些提示，只需在项目中放置一个 Claude Code allowlist 文件（.claude/settings.local.json）。这是一个静态的 Claude Code 设置文件，只是告诉 Claude Code“这些工具名称已获预先批准”——AIMFP 不会下载或执行该文件。

只需让 AI 为你设置：

"Set up AIMFP permissions for Claude Code"

AI 会调用 get_claude_permissions 工具，该工具会返回完整且最新的 allowlist（由工具注册表实时生成，因此内容永远不会过时或不完整）。随后，AI 会创建该文件；如果你已经有 .claude/settings.local.json，则会将内容合并到该文件中。合并会保留所有非 AIMFP 权限和你已有的其他设置；只有 AIMFP 条目会被更新。每个工具都会以 Claude Code 可能使用的两种名称加入 allowlist——mcp__aimfp__*（.mcp.json 服务）和 mcp__plugin_aimfp_aimfp__*（插件）——因此，无论采用哪种安装方式，该文件都适用。AIMFP 本身绝不会写入该文件（它绝不会触碰项目以外的内容）——由 AI 使用正常的文件写入确认来完成。你批准的唯一一次提示就是首次调用 get_claude_permissions，之后便无需再批准其他调用。

两个 MCP 自动启动键（enableAllProjectMcpServers 和 enabledMcpjsonServers）会自动包含在内，这样当项目中有 .mcp.json 时，AIMFP 服务就会自动启动。

注意：你也可以在 documentation/settings.local.json 找到随附的预构建 allowlist 副本，以便直接查看或手动复制（cp documentation/settings.local.json /path/to/your/project/.claude/）。推荐使用 get_claude_permissions 工具，因为它始终与已安装版本保持同步。

其他 MCP 客户端

该服务使用 stdio 传输。将客户端指向 python3 -m aimfp（或你的 venv 中 Python 的完整路径）。手动安装时，请确保 PYTHONPATH 包含 aimfp/ 文件夹的父目录。无需 API 密钥或身份验证。

工作原理

该服务使用模型上下文协议，通过 stdio 进行通信。它会根据自身的安装位置解析 aimfp_core.db（指令数据库）——无需环境变量。

连接后，AI 会在每次交互时调用 aimfp_run()（由系统提示词引导）。项目状态存储在工作目录中的 .aimfp-project/ 内，该目录会在初始化项目时自动创建。

项目初始化

告诉你的 AI 助手：

"Initialize AIMFP for my project"

AI 会调用 aimfp_init，在项目根目录中创建一个 .aimfp-project/ 文件夹，其中包含用于跟踪项目状态和用户偏好的数据库，以及一份 ProjectBlueprint 文档。你无需操作这些文件——MCP 服务会自动管理它们。

---

指令系统

FP 基线与 FP 指令

FP 基线（始终启用）：

• AI 编写代码时会自然遵循的核心函数式编程规则
• 纯函数、不可变性、不使用 OOP、显式错误处理
• 不可妥协——所有代码都必须符合 FP 规范

FP 指令（参考文档）：

• 针对复杂场景和边缘情况的详细指导
• 仅在 AI 不确定如何实现时查阅
• 类别：纯粹性、组合、错误处理、消除 OOP、优化
• 示例：fp_purity、fp_monadic_composition、fp_result_types、fp_wrapper_generation

项目指令

管理项目生命周期：

级别	指令	用途
级别 0	aimfp_run	网关编排（每次交互）
级别 1	aimfp_status、aimfp_init、project_task_decomposition	状态、初始化、高层协调
级别 2	project_file_write、project_update_db、project_task_update	操作执行
级别 3	project_compliance_check、project_evolution	状态管理
级别 4	project_completion_check、project_archive	验证与完成

用户偏好指令

管理 AI 行为定制与学习：

指令	用途
user_preferences_sync	在执行指令前加载偏好设置
user_preferences_update	将用户请求映射到指令，并更新偏好设置
user_preferences_learn	从用户更正中学习（需要确认）
user_preferences_export	将偏好设置导出为 JSON，以便备份或分享
user_preferences_import	从 JSON 文件导入偏好设置
project_notes_log	根据指令上下文将日志记录到 project.db
tracking_toggle	启用/禁用跟踪功能，并提示令牌成本

用户自定义指令

仅适用于用例 2：由 AIMFP 生成并管理代码库的自动化项目：

指令	用途
user_directive_parse	解析 YAML/JSON/TXT 指令文件，并提取结构化指令
user_directive_validate	通过交互式问答验证指令，消除歧义
user_directive_implement	在 src/ 中生成符合 FP 规范的实现代码
user_directive_approve	在启用前进行用户测试和审批的工作流
user_directive_activate	将指令标记为已启用（不会部署——由你的运行器负责）
user_directive_monitor	事后查看运行状况、统计数据和错误（只读）
user_directive_update	处理指令源文件的变更（重新解析、重新验证）
user_directive_deactivate	将指令标记为已暂停（不会停止正在运行的进程）
user_directive_status	全面报告所有用户指令的状态

用例（自动化项目）：

• 家庭自动化：「下午 5 点关闭客厅灯」、「如果炉灶开启超过 20 分钟，就将其关闭」
• 云基础设施：「CPU 使用率超过 80% 时扩展 EC2」、「每天凌晨 1 点备份 RDS」
• 自定义工作流：「每周一生成报告」、「自动处理上传的文件」

关键架构：

• 用户编写指令定义（YAML/JSON/TXT）
• AIMFP 生成完整的自动化代码库（src/、tests/ 等）
• AIMFP 像管理任何软件项目一样管理生成的代码（任务、文件、函数）
• AIMFP 从不执行指令，也从不监督运行器——生成的代码负责计时和执行工作；AIMFP 通过 aimfp.hooks 库 API 回答「何时到期」，并记录「发生了什么」
• 无需检查任何进程即可检测到运行器已停止：运行器声明下一次触发时间，超过该截止时间仍无响应即为证据
• Project.db 跟踪生成的代码；user_directives.db 跟踪指令状态

主要功能：

• 使用 YAML、JSON 或纯文本编写指令
• AI 通过交互式问答进行验证
• AI 在 src/ 中生成完整且符合 FP 规范的 Python 模块
• AI 为生成的代码创建测试
• 由你自己的调度器驱动执行，并通过 AIMFP 钩子库记录
• AIMFP 写入基于文件的日志（30 天的执行日志、90 天的错误日志），确保每个自动化项目的记录格式一致
• 会话开始时报告运行状况：逾期、跳过、降级、从未运行或出错
• 管理依赖项，并征求用户确认

指令定义示例：

# directives/home_automation.yaml (user creates this in their project)
directives:
  - name: turn_off_lights_5pm
    trigger:
      type: time
      time: "17:00"
      timezone: America/New_York
    action:
      type: api_call
      api: homeassistant
      endpoint: /services/light/turn_off
      params:
        entity_id: group.living_room_lights

用户对 AI 说：「解析我的指令文件 directives/home_automation.yaml」

AI 生成的代码（位于 src/lights_controller.py）：

# Auto-generated from home_automation.yaml
from typing import Result
from homeassistant_client import HomeAssistant

def turn_off_living_room_lights(ha_client: HomeAssistant) -> Result[None, str]:
    """Turn off all lights in living room group."""
    # FP-compliant implementation
    ...

完整的工作流文档请参阅 src/aimfp/reference/directives/ 中的指令 MD 文件。

Git 集成

由 FP 驱动的 Git 协作，支持多用户和多 AI 开发：

指令	用途
git_init	初始化 Git 仓库或与现有仓库集成，以进行版本控制
git_detect_external_changes	检测在 AIMFP 会话之外进行的代码修改
git_create_branch	创建用户/AI 工作分支（aimfp-{user}-{number}）
git_detect_conflicts	在合并前进行由 FP 驱动的冲突分析
git_merge_branch	合并分支并使用 AI 辅助解决冲突
git_sync_state	将 Git 哈希与 project.db 同步，以检测外部更改

主要功能：

• 多用户协作：多位开发者和 AI 实例可同时工作
• 由 FP 驱动的冲突解决：利用纯度等级、依赖关系和测试结果自动解决冲突
• 分支命名：aimfp-alice-001、aimfp-bob-002、aimfp-ai-claude-001
• 自动解决：使用 FP 纯度规则自动解决高置信度（>0.8）的冲突
• 外部更改检测：比较 Git HEAD 与存储的哈希，以检测在 AIMFP 之外进行的更改
• 简化的架构：无需单独的 git_state 表 — Git 命令足够快（约 1ms）

为什么 AIMFP + Git 优于 OOP + Git：

OOP 合并问题	AIMFP FP 解决方案
类层次结构冲突	✅ 无类 → 无层次结构冲突
隐式状态更改	✅ 纯函数 → 输入/输出明确
到处都是副作用	✅ 副作用隔离 → 冲突易于识别
难以测试两个版本	✅ 纯函数 → 易于测试和比较

冲突解决示例：

Alice and Bob both modify calculate_total():

Alice's version:
- Purity: ✅ Pure function
- Tests: 10/10 passing

Bob's version:
- Purity: ✅ Pure function
- Tests: 12/12 passing (includes edge cases)

AI Recommendation: Keep Bob's version (confidence: 85%)
Reason: More comprehensive tests, still pure

完整的多用户协作工作流请参阅 src/aimfp/reference/directives/ 中的 Git 指令 MD 文件。

---

项目生命周期

graph TD
    A[aimfp_init] --> B[project_discovery]
    B --> C[project_progression]
    C --> D[project_file_write]
    D --> E[project_update_db]
    E --> F{All Items Done?}
    F -->|No| D
    F -->|Yes| G[project_task_complete]
    G --> H{All Tasks Done?}
    H -->|No| C
    H -->|Yes| I[project_milestone_complete]
    I --> J{All Milestones Done?}
    J -->|No| C
    J -->|Yes| K[project_completion_check]
    K --> L[project_archive]

---

工作流示例

创建项目

User: "Help me build a matrix calculator"

AI → aimfp_run(is_new_session=true)
    → Receives: session bundle (directive names, status, settings, supportive context)
    → Checks project state: .aimfp-project/ missing → not initialized
    → Calls aimfp_init helper (Phase 1: mechanical setup)
        → Creates .aimfp-project/ directory
        → Creates project.db, user_preferences.db
        → Copies ProjectBlueprint template
    → Enters Phase 2 (intelligent population)
        → Detects language, build tool, source directory
        → Discusses with user: project name, purpose, goals
        → Updates infrastructure table and blueprint
    → Routes to project_discovery
        → Collaborates with user on themes, flows, completion path, milestones

AI: ✅ Project initialized: MatrixCalculator
    Next: Let's define the project shape — themes, completion path, and first milestones.

编写函数

User: "Write multiply_matrices function"

AI → aimfp_run() (continuation — lightweight guidance)
    → Evaluates: coding task + project tracking needed
    → Has directives cached from session bundle
    → Writes FP-compliant function naturally (pure, immutable, no OOP)
    → Follows project_file_write directive workflow:
        → Reserves file and function IDs in project.db
        → Writes src/matrix.py with embedded IDs
        → Finalizes file and function entries
        → Updates project.db:
           • files table (new entry)
           • functions table (multiply_matrices)
           • interactions table (dependencies)

AI: ✅ Function written: multiply_matrices
    File: src/matrix.py:15
    DB Updated: ✓ files, functions, interactions
    Dependencies: validate_dimensions

检查合规性

User: "Check project compliance"

AI → aimfp_run() (continuation — lightweight guidance)
    → project_compliance_check directive (opt-in tracking feature)
    → Queries all functions from project.db
    → Reviews each function against FP baseline
    → Generates analytics report

AI: 📊 Compliance Report:
    Total functions: 12
    Compliant: 10
    Violations: 2
      - calculate_discount (uses global config)
      - process_order (hidden mutation)

自定义 AI 行为

User: "Always add docstrings to functions"

AI → aimfp_run() (continuation — lightweight guidance)
    → user_preferences_update directive
        → Calls find_directive_by_intent helper
        → Searches directives by name/description/keywords
        → Finds match: project_file_write
        → Confirms with user: "Apply to file writing?"
        → Updates user_preferences.db

AI: ✅ Preference saved: project_file_write
    Key: always_add_docstrings
    Value: true

    Next file write will include docstrings automatically.

AI 从纠正中学习

User: "Actually, use guard clauses instead of nested if statements"

AI → user_preferences_learn directive (detects correction)
    → Logs interaction to ai_interaction_log
    → Infers preference: prefer_guard_clauses = true
    → Prompts user: "Should I remember this preference?"

User: "Yes"

AI: ✅ Preference learned: project_file_write
    Key: prefer_guard_clauses
    Value: true

    I'll use guard clauses in future functions.

---

文档

指令参考

所有指令文档均随软件包提供，位于 src/aimfp/reference/directives/ — 共 131 个 MD 文件，涵盖所有指令。每个文件都包含：用途、适用时机、完整工作流（主干 → 分支）、合规/不合规示例、边缘情况、相关指令、所用辅助函数以及数据库操作。

数据库架构

架构 SQL 文件位于软件包的 src/aimfp/database/schemas/ 中：

• aimfp_core.sql — 全局只读数据库（指令、辅助函数、流程）
• project.sql — 每个项目的可变数据库（文件、函数、任务、里程碑）
• user_preferences.sql — 每个项目的用户自定义数据库
• user_directives.sql — 每个项目的自动化指令（仅限用例 2）

---

开发

开发目录（dev/）

dev/ 目录包含指令和辅助函数定义的权威来源。这些 JSON 文件是规范定义，发布前会导入 aimfp_core.db。

dev/
├── directives-json/              # Directive definitions (source of truth)
│   ├── directives-fp-core.json   # Core FP directives
│   ├── directives-fp-aux.json    # Auxiliary FP directives
│   ├── directives-project.json   # Project lifecycle directives
│   ├── directives-user-pref.json # User preference directives
│   ├── directives-user-system.json # User automation directives
│   ├── directives-git.json       # Git collaboration directives
│   ├── directive_flow_fp.json    # FP directive flow transitions
│   ├── directive_flow_project.json # Project directive flow transitions
│   └── directive_flow_user_preferences.json # User pref flow transitions
├── helpers-json/                 # Helper function definitions (source of truth)
│   ├── helpers-core.json         # Core/directive helpers
│   ├── helpers-orchestrators.json # Entry point and status helpers
│   ├── helpers-project-*.json    # Project management helpers (9 numbered files)
│   ├── helpers-project-modules.json    # Module helpers
│   ├── helpers-project-task-files.json # Task-file link helpers
│   ├── helpers-catalog.json      # Existing-codebase adoption helpers
│   ├── helpers-changeset.json    # Semantic changeset merge helpers
│   ├── helpers-backup.json       # Backup helpers
│   ├── helpers-notices.json      # One-time release notice helpers
│   ├── helpers-settings.json     # User preference helpers
│   ├── helpers-user-custom.json  # User directive helpers
│   ├── helpers-git.json          # Git operation helpers
│   └── helpers-index.json        # Shared/global helpers
├── notices-json/notices.json     # One-time release notices (synced into aimfp_core.db)
├── sync-directives.py            # Imports JSON → aimfp_core.db
├── bump-version.py               # Syncs the package version across the files below
└── logs/                         # Development logs

开发工作流：修改 dev/ 中的 JSON 文件 → 删除 src/aimfp/database/aimfp_core.db 并运行 sync-directives.py 重新构建它 → 测试 → 发布。最终用户只会与预填充的 aimfp_core.db 交互，不会直接接触 JSON 文件。

版本位置

更新版本号时必须保持以下四处同步（python3 dev/bump-version.py 会完成此操作）：

文件	变量	用途
pyproject.toml	version = "X.Y.Z"	软件包版本（PyPI、pip install）
src/aimfp/__init__.py	__version__ = "X.Y.Z"	运行时版本（import aimfp; aimfp.__version__）
src/aimfp/mcp_server/server.py	SERVER_VERSION = "X.Y.Z"	MCP initialize 握手响应（serverInfo.version）
.claude-plugin/plugin.json	"version": "X.Y.Z"	Claude Code 插件版本

---

设计理念

规则不可变，项目持续演进

• aimfp_core.db 是规则手册（只读、全局、受版本控制）
• project.db 是工作区（可读写、按项目划分、保存运行时状态）
• user_preferences.db 是自定义层（可读写、按项目划分、定义 AI 行为）
• 指令划定边界；AI 在边界内自由运行

数据库驱动的上下文

传统 AI 助手缺乏持久记忆。AIMFP 解决了这个问题：

-- AI remembers everything across sessions via helper tools
AI calls: get_project_status("detailed")
→ Returns: project metadata, active milestone, current task, recent notes, tracked files and functions

-- No source code reparsing required. Instant context retrieval.

以有限性为设计原则

每个 AIMFP 项目都有一条完成路径：

Setup → Core Development → Testing → Documentation → Finalization

project_completion_check 通过后，项目即告完成。不再无休止地增加功能。

---

功能

• 全面的 MCP 工具 — 为 4 个 SQLite 数据库提供完整的增删改查功能，涵盖项目管理、FP 指令、用户偏好和自定义自动化指令
• 纯函数式约束 — AI 默认编写符合 FP 规范的代码（纯函数、不可变性、不使用 OOP）
• 数据库驱动的持久记忆 — 项目状态可跨会话保留，不会丢失上下文
• 基于指令的工作流 — 确定性的主干 → 分支 → 回退执行模式
• 有限的完成路径 — 项目设有明确的阶段、里程碑和任务；工作逐步收敛至完成
• 两种用法 — 常规软件开发（用例 1）或自定义指令自动化（用例 2）
• 用户偏好学习 — AI 通过针对每条指令的键值覆盖项，适应编码风格
• Git 集成 — 由 FP 驱动的分支管理和冲突解决
• 最少依赖 — 一个运行时包（watchdog）；自定义 JSON-RPC 服务仅使用标准库
• 注重成本的设计 — 默认禁用所有跟踪和分析功能

Token 开销

AIMFP 的项目管理会为每个会话增加 Token 开销。数据库操作（跟踪文件、更新任务、管理里程碑）会在编写代码之外消耗 Token。我们致力于将其降至最低——续接调用开销较低（约 2k Token），批处理辅助工具可减少往返次数，且默认关闭所有可选跟踪功能。

项目规模越大，收益越明显。不使用 AIMFP 时，每次新会话都需要 AI 重新扫描目录、重新读取源文件，并从头重建上下文；这些成本会随着代码库规模增长。使用 AIMFP 时，数据库可立即提供结构化上下文：AI 能准确了解有哪些文件、文件中包含哪些函数、工作进展到哪里，以及接下来要做什么。对于文件不止寥寥几个的项目，通过省去重复探索工作，前期跟踪成本可以获得多倍回报。

---

使用示例

示例 1：初始化项目

用户提示：“帮我制作一个计算器”

工具调用：

1. aimfp_run(is_new_session=true)
   → Returns: session bundle (directive names, settings, project status, supportive context)
   → Status shows: .aimfp-project/ missing — not initialized

2. aimfp_init(project_root="/home/user/calculator")
   → Returns: { success: true, message: "Project initialized" }

执行过程：

• AI 检测到尚无项目，并自动调用 aimfp_init 辅助工具
• 创建 .aimfp-project/ 目录，其中包含 project.db、user_preferences.db 和 ProjectBlueprint.md
• 注册项目元数据（名称、根路径、基础设施）
• 插入默认用户设置和备份配置
• AI 进入阶段 2：与用户讨论项目形态（基础设施、用途、目标）
• 路由至 project_discovery，协作制定计划（主题、流程、完成路径、里程碑）

示例 2：编写符合 FP 规范的代码

用户提示：“编写一个 multiply_matrices 函数”

工具调用：

1. aimfp_run(is_new_session=false)
   → Returns: lightweight guidance

2. reserve_file(name="matrix_operations", path="src/matrix_operations.py", language="Python")
   → Returns: { success: true, id: 42 }

3. reserve_function(name="multiply_matrices", file_id=42, purpose="Multiply two matrices")
   → Returns: { success: true, id: 99 }

   (AI writes FP-compliant code to src/matrix_operations_id_42.py)

4. finalize_file(file_id=42, path="src/matrix_operations_id_42.py", ...)
   → Returns: { success: true }

5. finalize_function(function_id=99, name="multiply_matrices_id_99", file_id=42, purpose="...", parameters=[...], returns={...})
   → Returns: { success: true }

执行过程：

• 编写前，先在 project.db 中预留文件和函数（将 ID 嵌入名称）
• AI 按照 FP 基线编写纯函数式代码（不使用 OOP、不进行修改、参数显式）
• 补充用途、参数和返回值元数据，完成文件和函数的登记
• 项目数据库现在会跟踪代码结构，以便在后续会话中即时检索

示例 3：恢复工作／查看状态

用户提示词：“进展如何？”或“继续工作”

工具调用：

1. aimfp_run(is_new_session=false)
   → Returns: guidance + common starting points

   (AI answers from cached context — no additional DB calls needed
    unless context is stale, in which case:)

2. aimfp_status(type="detailed")
   → Returns: project metadata, active milestone, current task, recent notes, warnings

执行效果：

• AI 会显示当前里程碑、正在进行的任务和后续步骤
• 如果 project_continue_on_start=true，AI 会自动开始下一个任务
• 无需重新解析源代码——所有内容都已编入 project.db 索引

---

隐私政策

AIMFP 完全在你的本地计算机上运行。没有任何数据会离开你的计算机。

• 无网络请求：MCP 服务不会发起任何网络调用。所有操作都是本地 SQLite 数据库读写和文件系统操作。
• 无遥测：不会收集或传输使用情况分析、崩溃报告或诊断数据。
• 无第三方服务：AIMFP 不会连接任何外部 API、云服务或远程服务。
• 仅限本地数据：所有项目数据（数据库、偏好设置、指令）都存储在项目的 .aimfp-project/ 目录中。所有数据均由你拥有和控制。
• 不访问 Claude 记忆：AIMFP 不会访问或读取 Claude 的对话历史、记忆或任何其他客户端数据。

如果你对数据处理有疑问，请在我们的 GitHub 仓库中提交 issue。

---

支持

• 问题反馈：GitHub Issues
• 仓库：github.com/aryanduntley/aimfp

---

贡献

AIMFP 是一项面向 AI 优化编程的开放标准。欢迎贡献：

1. 新的 FP 指令——特定语言或高级模式
2. 辅助函数——数据库、文件、Git 或 FP 工具
3. 模板——ADT 样板代码、错误处理模式
4. 文档——示例、教程、案例研究

提交贡献（拉取请求、补丁或其他材料）即表示你同意该贡献可依据 PolyForm Noncommercial License 1.0.0 以及版权持有人为 AIMFP 授予的任何商业许可进行分发，并确认你有权授予该许可。

---

许可证

AIMFP 采用 PolyForm Noncommercial License 1.0.0 许可。完整条款请参阅 LICENSE。

**可免费用于非商业用途：**个人学习、研究、实验、业余项目，以及慈善组织、教育机构、公共研究组织和政府机构的使用。

**商业用途需要获得书面批准。**这包括任何营利性用途，例如企业使用或为企业使用、用于有偿工作或客户项目、销售或再分发 AIMFP 或其衍生版本，以及将其作为付费产品或服务的一部分提供。如需申请商业许可证，请联系 Aryan Duntley：[email protected]。

截至 1.66.1（含）的版本依据 MIT License 发布，这些版本的副本仍受 MIT License 约束。此后的所有版本仅依据 PolyForm Noncommercial License 1.0.0 许可。

---

总结

AIMFP 将 AI 从“代码生成器”转变为结构化、可定制的项目协作者。

它结合了：

• 纯函数式编程，实现确定性、可组合的代码
• 四数据库架构，用于管理不可变规则、运行时状态、用户自定义内容和可选自动化
• 基于指令的工作流，实现一致、自动化的合规
• 用户偏好学习，让 AI 适应你的编码风格
• 有限的完成路径，支持以目标为导向的开发
• 注重成本的设计，提供可选启用的跟踪功能

最终成果：由 AI 维护的代码库在不同会话、团队乃至不同 AI 助手之间都能保持可预测、可追溯、可定制且易于维护。

---

为 AI 原生开发时代打造。