project-router

project-router 是 Safa 推出的终端优先型项目管理与上下文切换控制中枢，采用 CLI 与 MCP 服务器双模式架构，旨在解决多项目并行开发中的环境切换与任务追踪痛点。

核心用法围绕 .project/ 本地目录展开，该目录作为项目上下文核心，包含 project.json 结构化清单、PROJECT.md 动态简报、targets.json 构建目标定义及历史记录。用户可通过 project detect 自动识别项目，project context 加载上下文，或使用 project target run <name> 执行标准化构建、测试、部署流程。项目管理（PM）模块提供基于 SQLite 的本地 canonical 存储，支持任务增删改查与状态流转（Inbox/Next/Doing/Blocked/Waiting/Done），并通过 project pm switch/focus 实现快速上下文切换，自动加载关联文档与代码索引。此外，系统提供 Trello 双向同步适配器，将本地任务状态映射至看板卡片，实现终端与可视化界面的无缝协作。

显著优点在于其本地优先（Local-first）架构：零外部 npm 依赖，仅使用 Node.js 内置模块，彻底规避供应链攻击风险；采用 plan/apply 安全模式进行项目变更，确保操作可审计、可回滚；上下文切换功能（switch/focus）能根据项目或任务 ID 精准加载相关文档、代码与产物，大幅提升多项目并行效率；Trello 集成采用幂等性设计（upsert by task_id），重复同步不会重复创建卡片；MCP 服务器支持使 AI Agent 可直接调用项目检测、上下文读取与目标执行能力。

潜在局限包括：上游来源为个人开发者（T3），长期维护稳定性需观察；命令执行依赖用户手动配置的 targets.json，缺乏二次确认机制，若配置不当存在命令注入风险；Trello 同步需额外配置 API 密钥与看板权限，初期设置成本较高；对于非技术用户，终端优先的交互模式存在学习曲线；大文件（>2MB）会被索引跳过，可能影响特定场景下的产物管理。

适合人群主要为多项目并发的软件开发者、追求终端工作流（Terminal-first）的工程师、需要标准化构建与部署流程的 DevOps 团队，以及希望将本地开发状态与 Trello 看板同步的项目管理者。

使用风险方面，虽然代码本身无动态执行与远程加载，但 project_target_run 会执行用户配置文件中的 shell 命令，若从不信任来源获取的项目中直接运行，可能执行恶意命令（如 rm -rf 伪装成构建命令）。建议在使用前审查 .project/targets.json 内容。此外，SQLite 数据库与 .project 目录的本地存储需定期备份，防止数据丢失。Trello 同步功能涉及网络请求，需确保 API 密钥妥善保管，避免泄露。

核心功能

project-router 是 Safa 生态的权威项目管理工作流控制平面，采用 Terminal-first 设计，提供 CLI 与 MCP 服务器双接口，解决多项目开发中的上下文切换效率问题。

三大核心模块：

1. 项目检测与初始化：project detect 自动识别当前仓库结构，project init 通过 plan/apply 模式安全创建 .project/ 配置包（含 project.json、PROJECT.md、targets.json、artifacts 索引），确保所有变更可追溯。

2. 标准化目标执行：基于 .project/targets.json 定义构建/测试/部署命令，通过 project target run <name> 或 MCP 工具 project_target_run 执行，支持跨项目统一脚本规范。

3. 上下文切换与任务管理：project pm switch <slug> 加载项目关联文档、代码索引与活跃任务；project pm focus <taskId> 进一步聚焦至单任务上下文，自动关联文件与工件。配合 SQLite 本地数据库与 Trello 双向同步，实现"本地权威 + 可视化看板"的混合工作流。

显著优点：

• 零外部依赖：纯 Node.js 内置模块（fs/path/child_process）实现，根除供应链攻击面
• 安全设计：命令执行严格限定于用户自配置的 targets.json，plan/apply 模式防止误操作，所有文件操作 sandbox 在 .project/ 目录内
• 开放集成：MCP 服务器协议支持，可与任意 AI IDE 或自动化工具链对接

潜在局限：

• T3 来源：个人开发者维护，虽代码可追溯但缺乏组织级背书
• 基础输入校验：依赖简单 argv 解析，生产环境需自行加固参数验证
• shell: true 风险：target 命令执行使用 shell 模式，虽为功能必需但理论上存在注入可能（已通过用户配置限定缓解）

适合人群：追求终端效率的独立开发者、需要多项目快速切换的技术负责人、希望统一团队构建规范的工程管理者。

常规风险：Trello API 令牌需用户自行配置保管；SQLite 数据库建议定期备份；target 命令应避免配置 rm -rf / 类高危操作。